Bedrock Autoloader Laravel Package

Getting Started

• Install/upgrade with Composer: composer require roots/bedrock-autoloader:^2.0. In a stock Bedrock project this is already a dependency, so composer update roots/bedrock-autoloader is usually the only install step.
• Confirm your runtime is PHP 8.2+ before bumping — this is a hard requirement in 2.0 (#40). Check with php -v locally, in CI, and on the host.
• The autoloader is bootstrapped from a mu-plugin, not from config/. In Bedrock, look at web/app/mu-plugins/bedrock-autoloader.php first — it is the file you will almost certainly need to edit for 2.0.
• Replace the contents with the new snippet from the release notes. The important deltas vs. 1.x:
  • New namespace: Roots\Bedrock\Autoloader\Autoloader (note the doubled Autoloader).
  • The constructor now takes the mu-plugin path explicitly: new Autoloader(WPMU_PLUGIN_DIR).
  • You now call boot(), include the returned files yourself, then call markLoaded().
• First use case: add a Composer package with "type": "wordpress-muplugin" (or configure installer-paths for web/app/mu-plugins/{$name}/) and let it load automatically. The autoloader is what makes nested mu-plugin directories work, since WordPress only auto-includes .php files at the root of mu-plugins/.

Implementation Patterns

• Standard Bedrock setup. Keep web/app/mu-plugins/bedrock-autoloader.php as a thin entry point. Do not put logic in it beyond the guard, construction, loop, markLoaded(), and unset().
• Guarding. Keep both guards from the reference snippet:
  • class_exists(\Roots\Bedrock\Autoloader\Autoloader::class) — prevents a fatal if Composer's autoloader hasn't run or the package is missing (common in minimal/CI installs).
• is_blog_installed() — avoids running before WordPress is installed, which matters during wp core install, container boots, and migrations.
• Return-value loop. boot() returns an array of file paths; the calling mu-plugin is responsible for include_once. If you need custom ordering or filtering, do it on that array before including — this is the cleanest extension point the package gives you.
• markLoaded(). Call it after the loop so the plugins table in wp-admin shows the asterisk that distinguishes autoloaded plugins from normal ones. Skip it and users lose the visual cue.
• Custom directories. Because the constructor is now side-effect-free and takes a path, you can point it at a non-default directory (e.g. a test fixture or a custom WPMU_PLUGIN_DIR). Pass the same constant WordPress uses, or your plugins will be scanned from the wrong place.
• Composer-first workflow. Bedrock projects manage mu-plugins through installer-paths; a typical entry looks like "web/app/mu-plugins/{$name}/": ["type:wordpress-muplugin"]. Add the package to require, run composer install, and rely on the loader rather than symlinks.
• Multi-file mu-plugins. Only subdirectory plugins are handled by the autoloader — flat .php files at the mu-plugins root are still loaded by WordPress itself. Keep that split in mind when debugging "why isn't this loading".
• Boot ordering. Bedrock's wp-config.php requires vendor/autoload.php before mu-plugins run. If you're wiring this up outside Bedrock, replicate that order or the class_exists guard will silently short-circuit.

Gotchas and Tips

• The namespace change is the biggest trap. new \Roots\Bedrock\Autoloader(...) (v1.x) will fail the class_exists guard in 2.0 silently — no fatal, no log line, just plugins that mysteriously stop loading. Grep your codebase for the old namespace after upgrading.
• Composer version bump alone is not enough. The package can be 2.0 while mu-plugins/bedrock-autoloader.php is still the 1.x file. If your Bedrock repo vendors that file, update it in the same commit; otherwise the new side-effect-free constructor signature will not be used and boot()/markLoaded() never fire.
• Constructor is side-effect-free now. Anything you relied on happening at new Autoloader(...) time no longer happens. You must call boot() and markLoaded() explicitly.
• Global scope leakage (fixed in #44). Autoloaded mu-plugins previously ran in a scope where $file and $autoloader could leak into the included file. Don't write plugin code that depends on those variables — the fix removes them, and the trailing unset($autoloader, $file) in the reference snippet is there to keep the global scope tidy.
• Autoloaded plugins behave like mu-plugins. They can't be deactivated from wp-admin in the normal way, which regularly confuses editors. The asterisk from markLoaded() is the only signal — make sure it works.
• Debugging checklist: confirm vendor/autoload.php loads (class_exists returns true), confirm the path passed to the constructor is the real WPMU_PLUGIN_DIR, run wp plugin list to see whether entries appear, and check error_log for include_once warnings on missing files.
• Pre-release version. 2.0.0-beta.1 is not stable. Pin to the exact beta (or stay on 1.1.0) for production until 2.0.0 is tagged; expect the API surface to be settled but not guaranteed.
• Pint is now the style baseline (#41). If you vendor or fork this package, expect formatting diffs against the new Pint config — unrelated to behaviour, but noisy in a diff review.
• Extension point. There is no plugin/hook system in the package; if you need conditional loading, filter the array returned by boot() in your own mu-plugin wrapper rather than subclassing Autoloader.