Composer Include Files Laravel Package

Technical Evaluation

Architecture fit: This is a Composer plugin, not a Laravel package — no service provider, no publishable config, no framework lifecycle hooks. It operates at the autoload/bootstrap layer to force specific files to load before Composer's generated files autoload list. That is a narrow, deliberate escape hatch for one problem: declaring symbols before a dependency declares them. In a modern Laravel application this is almost always a smell. It is defensible for legacy upgrades or for third-party packages that ship unguarded global functions you must supersede. For greenfield work, architecture fit is poor.

Integration feasibility: Mechanically easy — require the plugin, list files under extra, dump autoload. The real feasibility question is environmental: Composer 2.2+ requires explicit allow-plugins consent, and the last release (Oct 2020) predates much of Composer 2's plugin API hardening. Feasibility must be proven against the project's exact Composer and PHP versions, not assumed from the README.

Technical risk: High relative to the problem being solved. Unmaintained since 2020, 125 stars, effectively single-maintainer, and it executes with Composer's privileges during install/update — a supply-chain surface. Correctness depends on the full dependency graph's autoload ordering, which changes on any composer update. Failure modes include PHP fatal redeclare errors, silent no-ops, and divergence between optimized/authoritative autoload builds and normal ones. Interactions with --no-dev, --classmap-authoritative, and OPcache preloading need explicit testing.

Key questions:

• Which exact symbol is being overridden, and is there a native extension point (container binding, macro, uniquely named helper, upstream patch)?
• Which Composer versions exist across developer machines, CI, and deploy images?
• Can we fork and pin the plugin, and who owns that fork?
• What automated test proves the include actually executed first?
• What is the exit criterion and review date?

Integration Approach

Stack fit: Framework-agnostic and therefore unmanaged by Laravel's lifecycle. That is a liability: no artisan command, no config cache integration, no obvious trace in the app. Before adopting, exhaust native options — service container bindings, macros, custom helpers with unique names, package configuration. Adopt only when a dependency defines an unguarded global function you cannot patch upstream.

Migration path: Treat it as a time-boxed exception, not a platform decision. Introduce on a branch with a short ADR, pin the exact plugin version, add the allow-plugins entry, and add a smoke test asserting the override is active. Run a full composer update cycle in staging. Define the exit path — upstream fix, maintained fork, or refactor — with a date attached.

Compatibility: Validate against the project's Composer major/minor, PHP versions, CI images, and deploy build steps. Test clean installs and updates, with and without the optimized autoloader, and with --no-dev. Commit the lock file and constrain composer-plugin-api where possible.

Sequencing:

1. Confirm the problem cannot be solved natively.
2. Spike in a disposable branch against the real dependency graph.
3. Add a CI guard test that fails if the override stops taking effect.
4. Document rationale, scope, and named owner.
5. Roll to staging, then production.
6. Schedule quarterly review and a formal exit checkpoint.

Operational Impact

Maintenance: Unmaintained upstream means the team effectively owns the code. Budget for occasional forks or patches, particularly at Composer and PHP upgrades. Dependency scanners will surface it; policy should classify it as an accepted, documented exception rather than letting it drift into silent technical debt.

Support: Community-only, no SLA, sparse issue activity. An internal runbook is mandatory: what the plugin does, which files are prioritized, how to diagnose a redeclare fatal, and how to disable it safely without breaking boot.

Scaling: Runtime cost is negligible. Organizational cost is not. Every new dependency can shift the autoload graph, and multiple teams adding priority includes creates undefined conflict resolution. Centralize to one owned configuration and forbid per-team usage.

Failure modes:

• Fatal redeclare in production after an ordering change.
• Install failure when allow-plugins is not configured on a new machine or CI runner.
• Silent no-op after a Composer upgrade, deferring failure to runtime.
• Dev/prod divergence caused by autoloader optimization flags.
• Security exposure through Composer-privileged third-party code.

Ramp-up: Low to install, high to reason about safely. Most engineers will not know it is present. Mitigate with the ADR, runbook, CI assertion, and an onboarding note naming the owner. Recommendation: adopt only as a documented tactical bridge with a funded exit plan; reject as a long-term platform dependency.