Laravel Package Toolkit Laravel Package

Product Decisions This Supports

• Modularization strategy: monolith vs. packages. If the roadmap includes carving domain capabilities (billing, tenancy, notifications, admin surfaces) into shareable packages, this toolkit directly lowers the cost and variance of each extraction. It is the "reusable module" play, not the "ship one app" play.
• Build vs. buy for internal scaffolding. Every Laravel package re-implements the same service-provider wiring — config publishing, routes, migrations, translations, views, middleware, commands, assets. This package is a candidate "buy" (MIT, zero license cost) that replaces a hand-rolled internal base class.
• Platform/DX roadmap. Choosing a canonical package skeleton is a platform-team decision that sets conventions for years: naming, publishing behavior, lifecycle hooks, conditional resource loading. It quietly becomes policy, so it deserves an explicit decision rather than an accretion of one-off composer.json copy-pastes.
• Multi-product and multi-client reuse. Particularly relevant to agencies, consultancies, and companies running several Laravel products where a shared package layer (auth, audit logging, feature flags) is the roadmap's connective tissue.
• AI-assisted engineering enablement. Unusually, the package ships an agent-facing surface — ai/AGENTS.md, a Claude Code skill, and a zero-dependency MCP server installed into consuming projects via vendor/bin/package-toolkit-ai install. That maps to a separate roadmap item (agent readiness of internal codebases) and is arguably its most differentiated feature.
• Feature-flagging / environment-scoped rollout. whenProduction(), whenLocal(), whenClassExists(), whenExtensionLoaded() give a supported pattern for loading commands and config only where appropriate — useful for a "no dev-only tooling in production" compliance decision.
• Security/maintenance posture decision. The v2.1 break dropping Laravel 10/11, explicitly tied to CVE-2026-48019 patching only in 12.60+/13.9+, is a forcing function: it aligns your package layer to a supported-version policy. That can support a roadmap decision to upgrade off end-of-life Laravel branches.
• Not a product-facing decision. Nothing here changes customer-visible behavior. Do not let it consume roadmap capacity beyond a bounded spike.

When to Consider This Package

Consider it when:

• Your team already maintains, or is about to maintain, three or more first-party Laravel packages. Below that threshold the boilerplate savings rarely pay for the added dependency and base-class coupling.
• You are on Laravel 12.x (≥ 12.61.1) or 13.x (≥ 13.12.0). The pinned minimums are a security requirement, not a suggestion.
• Package setup toil is a recurring, measurable tax — engineers rebuilding route/config/view registration per package, or packages drifting into inconsistent publishing and naming conventions.
• You want convention enforcement (kebab-case short names, eager validation, lifecycle hooks, a documented API surface) more than maximum flexibility.
• You are willing to own the risk: 0 stars, 0 dependents, and no consumer base means you are effectively adopting a solo-maintainer library. Adopt only if you can vendor or fork it and are comfortable reading its source.
• You value the agent/MCP tooling enough to justify the dependency on its own merits.

Look elsewhere when:

• You ship a single application with no package boundary. Laravel's own service provider API is sufficient; this is pure overhead.
• You are pinned to Laravel 10 or 11 (or 9). Use ~2.0.0/^1.0 only as a stopgap; you are adopting an unsupported branch of an already-low-adoption library.
• You need vendor guarantees — SLAs, security response commitments, a named maintainer team, or a track record of downstream usage.
• spatie/laravel-package-tools already covers your needs. It is the incumbent default with broad adoption; the burden of proof is on the challenger. Compare feature-by-feature before switching — the toolkit's differentiators appear to be lifecycle hooks, conditional registration, optimize-command wiring, broadcast channels, and the AI surface.
• The architecture is a poor fit: inheritance from PackageServiceProvider is a hard structural commitment. Teams preferring composition, or packages with unusual boot ordering, should not adopt.
• Your team lacks fluency in service provider internals. Debugging a third-party abstraction layer over framework boot order is an expensive place to learn.
• Roadmap horizon is short. Anything under roughly a year of expected package-layer life won't amortize the evaluation and vendoring cost.

Decision to make explicitly: adopt, vendor-and-fork, spike-only, or reject. Given the adoption signals, "vendor-and-fork with a pinned version" is the defensible middle; blanket "adopt as a dependency across all repos" is not.

How to Pitch It (Stakeholders)

For executives — one paragraph: This is an internal developer-efficiency library, not a customer-facing feature. It standardizes how we build reusable Laravel packages so engineers stop rewriting the same wiring for config, routes, migrations, views, translations, middleware, and commands. MIT-licensed, no purchase cost; the only cost is engineering attention. The strategic upside is speed and consistency when we extract shared capabilities into packages across products — plus an unusual bonus: it ships tooling that makes our codebases legible to AI coding agents, which supports our developer-productivity goals. The strategic risk is maturity: effectively zero public adoption and a single-maintainer profile, so we should treat it as code we may have to own, not a vendor we can lean on. Recommendation: a time-boxed spike against our existing packages, with a go/no-go gated on whether we can vendor it and whether it beats the incumbent spatie/laravel-package-tools for our actual use cases.

For engineering — the summary: Extend PackageServiceProvider, implement Packable, and declare your package in configure(Packager $packager) with a fluent, self-validating API (->name(), ->hasConfig(), ->hasRoutes(), ->hasMigrations(), …). It handles the register/boot work, adds lifecycle hooks (registeringPackage() / registeredPackage() / bootingPackage() / bootedPackage()), conditional resource loading (whenLocal(), whenProduction(), whenConsole(), whenClassExists()), middleware aliases/groups/globals, events and subscribers, broadcast channel files, optimize/optimize:clear commands, publishable seeders/factories/stubs, and an install command. Architecture is two-sided by design — src/Concerns/ declares on Packager, src/Support/Concerns/ acts on the provider — so plan for that split when extending it. Quality signals are respectable for a library this young: full Pest suite on Orchestra Testbench, PHPStan/Larastan level 7 on src, Pint-enforced formatting, a real docs site with per-resource pages and gotchas. Constraints to accept up front: PHP ^8.2, Laravel 12.61+/13.12+ only, inheritance-based coupling, and the fact that channel files are deliberately non-publishable (consumers override by re-registering). Cost of validation: a one-to-two-day spike, one package ported, compare diff size and boot-order surprises against the incumbent.

For the sponsor's decision log: Approve evaluation, not adoption. Success criteria: measurable reduction in per-package setup effort, no boot-order regressions, and a documented exit path (vendored fork under our maintenance if upstream stalls).