Composer Include Files Laravel Package

Getting Started

1. composer require funkjedi/composer-include-files — this installs a Composer plugin, so it must be in require (not require-dev).
2. On Composer 2.2+, allow the plugin explicitly:

   "config": { "allow-plugins": { "funkjedi/composer-include-files": true } }
   

3. Declare the files you want preloaded in extra.include_files on a package (or the root project):

   "extra": { "include_files": ["bootstrap/functions.php"] }
   

4. Run composer dump-autoload and inspect the generated vendor/composer/include_files.php plus vendor/composer/autoload_files.php to confirm your files are wired ahead of normal autoload.files.

First real use case: WordPress plugins/themes or legacy libraries where a bootstrap file must run before anything declared in other packages' autoload.files (constants, helper functions, polyfills that later files assume exist).

Implementation Patterns

• Library-authoring pattern (most common). Publish your package with extra.include_files. Consumers get the correct load order automatically — no require in their app bootstrap, no instruction in the README.
• Root aggregator pattern. If you can't modify a vendored package, declare its file in the root composer.json under extra.include_files. This is also the way to get deterministic ordering: put one aggregator file in the array that require_onces the rest in the order you want.
• Framework bootstrapping. Because the plugin wires into Composer's autoload_files bootstrap, the preloaded files run whenever vendor/autoload.php runs — so Laravel's index.php, a WordPress wp-load shim, or a CLI entrypoint will pick them up without extra glue.
• Multi-env setups. The list is resolved at dump time, not runtime. If you need different includes per environment, generate them via scripts (post-autoload-dump) or maintain separate root composer.json variants; don't expect env-based toggling.
• Deployment. Always run composer install --no-dev --optimize-autoloader (or at minimum dump-autoload) during deploy/CI so the generated file matches the lock file. Commit vendor/ only if you also commit the regenerated include file.

Gotchas and Tips

• Composer 2.2+ allow-plugins is the #1 cause of "package installed but nothing happened." Check the install output for "Plugin ... was skipped."
• Composer plugin API compatibility. The last release is 2020-10-26; verify its composer-plugin-api constraint accepts your Composer 2.x version before relying on it. Pin the version and test upgrades.
• Never hand-edit vendor/composer/include_files.php — it's regenerated on every install/update/dump and your changes vanish.
• Paths are relative to the declaring package's root, not the project root. A typo silently produces a file with a broken require.
• --no-scripts / COMPOSER_SKIP_SCRIPTS skips post-autoload-dump; the generated file goes stale or missing, and you'll chase a load-order bug that's really a build bug.
• Cross-package ordering is not contractual. Determinism is within a single package's array. If two packages both preload files that depend on each other, consolidate into one aggregator.
• Double-loading. Composer dedupes by file hash, but if your own code also requires the same file, use require_once to avoid redefining functions/classes.
• Debugging: COMPOSER_DEBUG_EVENTS=1 composer dump-autoload -vvv, then read vendor/composer/include_files.php and grep autoload_files.php for your paths.
• Escape hatch: root extra.include_files is the recommended extension point for code you don't own; it keeps the override visible in version control instead of buried in vendor.
• Maintenance risk. With a 2020 last release and no active repo, plan the exit: a tiny hand-written bootstrap that explicitly require_onces the same files before vendor/autoload.php is a drop-in replacement when you outgrow the plugin.