Composer Exclude Files Laravel Package

Product Decisions This Supports

• Performance budget / bootstrap-cost reduction. Every entry in Composer's generated autoload_files.php is required on every request. This package lets you drop specific eagerly-loaded files without forking the dependency, so it directly supports decisions like "is shaving N file includes per request worth an engineering afternoon?" — usually yes on high-traffic endpoints, rarely on admin-only surfaces.
• Third-party dependency triage (build vs. buy vs. fork). When a vendor package ships a files autoload that conflicts with ours, defines functions we already have, or pulls in side effects at boot, the usual menu is: fork it, replace it, patch it after install, or exclude the file. This package makes "exclude the file" a first-class, declarative option — a cheaper build-vs-buy answer than maintaining a fork.
• Package evaluation criteria. It gives the team a concrete rubric item for future dependency reviews: does this package declare autoload.files, and is that file essential at boot? Roadmap implication: standardize lazy-loading for helper files in our own first-party packages so we never need the workaround.
• Supply-chain and blast-radius decisions. Files loaded at boot run on every request, including health checks and public endpoints. Excluding non-essential ones narrows the code that executes unconditionally — relevant when assessing a new dependency's risk profile.
• Remediation path for environment-specific breakage. E.g., a package's helper file requires a PHP extension or env var not present in one deployment target. Excluding it locally buys time without blocking a release.
• Roadmap signal: adoption here is a smell. If you need this plugin, you likely have a dependency hygiene problem worth a quarterly cleanup item — file per exclusion, revisit and remove.

When to Consider This Package

Consider it when:

• Profiling or strace/opcache analysis shows measurable per-request cost from autoload_files.php, or a specific included file is genuinely unused in your code paths.
• A dependency's boot-time file causes a hard conflict (duplicate function/class), emits output, or performs I/O you don't want on every request.
• You cannot or will not fork the upstream package — vendor code you don't own, a package you'd rather keep on the upgrade path, or a one-line internal hotfix that would be lost.
• You need a declarative, reviewable exclusion list in composer.json rather than a post-install script that mutates vendor/ (which is invisible to code review and breaks on composer install ordering).
• You're on Composer 2 with allow-plugins under control and you pin versions in composer.lock.

Look elsewhere when:

• You own the package — fix the autoload.files declaration upstream and delete the workaround; permanent fixes beat permanent exclusions.
• You want the whole package gone: use replace, a fork, or simply don't install it. This plugin is a scalpel, not a dependency remover.
• The problem is at runtime (you want the file sometimes) — that's lazy loading in your own code, not a Composer concern.
• Your platform team forbids Composer plugins, or allow-plugins is centrally pinned and adding entries is a slow approval path — the coordination cost may exceed the benefit.
• The file you want to exclude is load-bearing (defines functions another package calls). Excluding it converts a performance issue into a fatal error; verify call sites first.
• You need guarantees across Composer major versions. It's a small plugin riding Composer internals; budget for re-validation on Composer upgrades.

Adoption caveats to weigh: ~40 stars and zero dependents means effectively no production track record — you are an early adopter. Single-maintainer bus factor, and the plugin sits in the critical path of composer install, so a break blocks every build. Counterweight: MIT license, tiny surface area, and a recent release date suggest it's maintained. Mitigation: pin exactly, commit the lockfile, document each exclusion with a reason and a removal trigger, and keep a fallback (--no-plugins plus manual patch) in the runbook.

How to Pitch It (Stakeholders)

For executives (30 seconds): Every PHP request to our Laravel apps loads a pile of helper files that third-party packages force in at boot — even when our code never uses them. This is a small, MIT-licensed Composer plugin that lets us opt out of specific files with one line of config, no forking and no patching. It's a low-cost lever on page latency and infrastructure cost, and it reduces how much unfamiliar code runs on every single request. The trade-off is that it's a young project with no visible adopters, so we'd pin it, document every exclusion, and treat it as a temporary measure with a cleanup date — not a permanent architectural commitment.

For engineering leads: It solves a real, annoying problem — removing a vendor's autoload.files entry without vendoring the package — and it does so declaratively in composer.json, which means the decision is code-reviewed and versioned instead of hidden in a post-install script. Costs: it's a Composer plugin (needs allow-plugins approval), it lives in the install critical path, and it's an escape hatch that can mask upstream bugs. Recommendation: pilot on one service where we have profile data, measure the delta, gate adoption on a written exclusion rationale per file, and require an upstream fix or removal within two quarters. Don't standardize org-wide on the strength of 40 stars.