Laravel Package Toolkit Laravel Package

Technical Evaluation

Architecture fit. This is a library for library authors, not an application dependency. Its unit of value is the Laravel package's ServiceProvider: instead of hand-writing mergeConfigFrom, loadRoutesFrom, loadMigrationsFrom, loadTranslationsFrom, loadViewsFrom, publish tags and optimizes(), a package author subclasses PackageServiceProvider, implements Packable, and declares intent in configure(Packager $packager). That is a thin decorator over well-known Laravel boilerplate, split deliberately into two collaborators — src/Concerns/ declares resources on Packager, src/Support/Concerns/ acts on them at register/boot. It fits cleanly wherever we own a portfolio of first-party Laravel packages (SDKs, internal platform modules, shared domain or UI packages). It does not belong in application code, and it is not a runtime framework concern.

Integration feasibility. Mechanically trivial: one composer require, one base class, one contract. No schema, no data migration, no service to operate. The real feasibility question is organizational — whether we want a single third-party base class in the inheritance path of every internal package.

Technical risk.

• Inheritance lock-in. extends PackageServiceProvider is a one-way door. Backing it out means rewriting every adopting package's provider.
• Concentration risk. One base class becomes a shared failure domain; a regression in a minor release can break boot across all adopters simultaneously.
• Adoption immaturity. 0 stars, 0 dependents. Engineering hygiene is visibly above average — Pest suite on Orchestra Testbench, PHPStan/Larastan level 7, Pint, changelog, docs site with per-resource pages plus /llms.txt, and a shipped ai/AGENTS.md + MCP server + Claude skill installed via vendor/bin/package-toolkit-ai install. But hygiene is evidence of care, not evidence of production use.
• Version velocity. v1 → v2 → v2.1 with Laravel 10/11 support removed. The stated rationale is legitimate (CVE-2026-48019, CRLF injection, patched only in Laravel 12.60+/13.9+ and never backported), but it means this library's support window is bolted to Laravel's, and the pins (>= 12.61.1, >= 13.12.0) are unusually specific.

Key questions.

1. Who maintains this, and is there a stated support policy or a second maintainer (bus factor)?
2. Is PackageServiceProvider covered by semver such that ^2.x is safe to trust on minors?
3. What is the security disclosure path, and how fast were the CVE-driven version pins turned around?
4. Does the abstraction diverge from upstream Laravel conventions in ways that would surprise a developer who knows vanilla packages?
5. What does the ai/ tooling read out of vendor/, and has that been reviewed?
6. Will the maintainer take changes we need, or does adoption imply a willingness to fork?

Integration Approach

Stack fit. Qualifies only if the roadmap includes authoring Laravel packages. Hard prerequisites: PHP ^8.2 and Laravel 12.x (≥12.61.1) or 13.x (≥13.12.0). Confirm the fleet's Laravel baseline first — that alone may defer the decision.

Migration path. Greenfield only, initially. New internal packages extend PackageServiceProvider from day one. Do not retrofit existing packages: converting a working provider buys no user-visible value and creates a rollback problem across every consumer. Packages still on Laravel 10/11 can only use ~2.0.0, which sits on an EOL, unpatched Laravel line — treat that combination as unsupported rather than as a compatibility option.

Compatibility. Map the package inventory against the matrix before committing: Laravel 9 → ^1.0; 10/11 → ~2.0.0 (not recommended); 12.61.1+/13.12.0 → ^2.1. Any package we intend to support beyond one Laravel major needs an exit plan regardless of this decision.

Sequencing.

1. Spike: port one small, low-risk package on a branch; measure lines removed and review the diff for readability, not just brevity.
2. Validate the docs and shipped agent assets by installing them into a consuming repo and checking the reference matches installed source.
3. If the spike holds, publish an internal convention: new packages use the toolkit, and resources are declared in configure(), not scattered across register()/boot().
4. Roll out to new packages only; revisit legacy conversion never, or only on a full rewrite.
5. Add a dependency-review gate so toolkit upgrades are read and tested, not auto-merged.

Operational Impact

Maintenance. Near-zero code maintenance inside our repos; the burden is dependency stewardship — reading changelogs, testing upgrades, watching Laravel-major coupling. Pin to a minor and bump deliberately. MIT licensing preserves a fork as the ultimate hedge, but forking a 0-star project means owning it outright.

Support. No vendor. Self-support plus upstream issues. Set that expectation with the team explicitly: this is a community dependency, not a supported platform component, and it should never sit under a customer-facing SLA without a fork contingency.

Scaling. Scales with package count, not traffic. Runtime cost is the provider boot plus whatever is declared; the when*() conditionals (whenLocal, whenProduction, whenConsole, whenClassExists, whenExtensionLoaded) exist precisely so dev-only resources don't load in production. The payoff compounds through consistency — many packages, one mental model, uniform publishing and install-command behavior.

Failure modes.

• Upstream abandonment or a stalled maintainer.
• A breaking minor release cascading across all adopters at once.
• Double registration when a package mixes toolkit declarations with leftover manual loadViewsFrom/publish calls.
• Silent misregistration from the custom-path and directory arguments (hasConfig([...]), hasRoute(directory: ...)) — wrong paths fail quietly rather than loudly.
• A new Laravel major landing before the toolkit supports it, blocking package upgrades.
• Broadcast::channel() files mistakenly routed through hasRoutes(), which loads them into the router rather than the broadcaster.

Ramp-up. Low for anyone fluent in Laravel package conventions — the fluent API mirrors Laravel's own idioms, and lifecycle hooks are named after the register/boot phases developers already know. The docs site, per-resource pages with gotchas, changelog, and the shipped agent assets (ai/AGENTS.md, the Claude skill, the MCP server answering from installed source) meaningfully shorten onboarding and answer questions in-editor. The counterweight is that it is one more abstraction and a second set of conventions alongside vanilla Laravel, so budget a short internal walkthrough and a review rule against hand-rolling what the packager already does.