Composer Include Files Laravel Package

Getting Started

This is a Composer plugin that lets any package in the dependency tree declare files to be required before Composer's PSR-4 classmap and autoload.files are loaded. That ordering is the whole point: constants, polyfills, and function shims that autoloaded code depends on must already exist when the first class file runs.

Minimal setup in your root composer.json:

{
    "require": {
        "0.0.0/composer-include-files": "^1.0"
    },
    "extra": {
        "include-files": [
            "bootstrap/constants.php",
            "bootstrap/polyfills.php"
        ]
    },
    "config": {
        "allow-plugins": {
            "0.0.0/composer-include-files": true
        }
    }
}

Then composer install (the install itself regenerates the autoloader). Note the allow-plugins block — on Composer 2.2+ the plugin is silently not executed without it, which is the first thing to check when "nothing happens".

Where to look when it works: after dumping, the plugin rewrites or wraps vendor/autoload.php and emits a generated include file under vendor/composer/ (something like composer/include-files.php). Read that generated file first — it tells you the resolved absolute paths and the exact ordering the plugin chose.

First use case: a Laravel package or app that needs define('MY_PKG_MODE', ...), a str_contains polyfill for PHP 7.x, or a class_alias() of a vendor class to a subclass — all of which break if placed in autoload.files next to code that consumes them.

Implementation Patterns

Package-level bootstrap (the real win). Because the plugin reads extra.include-files from every installed package, not just the root, a library you publish can ship its own bootstrap. A Laravel package can declare a constants file that its service provider needs, and consumers get correct ordering for free — no "files" autoload entry, no "class not found during provider registration" bugs.

Polyfill before classmap. Put compatibility shims in include-files rather than autoload.files. autoload.files are loaded in package order after the classmap is registered; include-files run before, so a class that is eagerly instantiated by another package's autoloaded file can still call str_contains().

Override-before-load. A common trick: declare a file that does class_alias(MyDecorator::class, Vendor\Service::class) or conditionally defines a function the vendor defines lazily. Because you run first, you can win the function_exists() race. Only do this where the vendor's own file guards with function_exists().

Keep the list tiny and split by concern. One file for constants, one for polyfills, one for aliases. Ordering within extra.include-files is preserved, but ordering across packages depends on install order, so never let two packages both depend on a shared constant being defined by the other.

In CI, always run composer dump-autoload -o as an explicit step (or use composer install in a clean tree). Incremental hand edits to vendor/autoload.php do not survive a dump, and reviewers who copy vendor/ between branches will get stale include lists.

Gotchas and Tips

• Silent no-op via allow-plugins. The most common failure. composer install succeeds, no files are included, no error. Run composer diagnose or check vendor/composer/installed.json for the plugin's "type": "composer-plugin" entry.
• Regeneration is a dump-time event. Changing extra.include-files requires composer dump-autoload. composer update does it; a bare composer require of an unrelated package does not always pick up your edits.
• Runs on every request, in every SAPI. These files execute for CLI commands, queue workers, and artisan too — not just HTTP. Keep them side-effect free and idempotent; a define() without defined() guard will emit a notice under -d error_reporting=E_ALL.
• Path resolution is per-package. Paths are relative to the package that declares them, not the root project. A path in a dependency's composer.json resolves inside vendor/, so a moved or path-repository package can break the include silently at runtime even though the dump "succeeded" — verify the resolved path in the generated vendor/composer/include-files.php.
• Don't rely on include-files for anything loaded before Composer's own autoloader — environment bootstrap, index.php wiring, other Composer plugins. The first Composer plugin to load wins, and this plugin is itself loaded by the autoloader it is modifying.
• composer.lock and commits. Pin the plugin to a tag or commit SHA; this is a low-traffic fork (12 stars, score 0.15) of fkrauthan/composer-include-files. If upstream fixes a Composer 2.x regression you care about, you are not on that train. For production apps where you have no ordering need, plain autoload.files is the lower-risk choice.
• Debugging: temporarily add fwrite(STDERR, __FILE__."\n") to the top of each include file, or run composer dump-autoload -vvv and grep for the plugin's output. If the generated file exists but nothing loads, your vendor/autoload.php was regenerated by a tool that bypassed the plugin (e.g. a --no-plugins install, common in hardened Docker builds — check COMPOSER_NO_PLUGINS).
• Extension point: the plugin hangs off post-autoload-dump; if you need conditional inclusion, wrap the logic in the include file itself rather than trying to make the list dynamic — the list is baked into the generated file.