Composer Wordpress Autoloader Laravel Package

Getting Started

1. Install as a runtime dependency (not --dev) if your plugin/theme's own classes rely on it, since the generated loader is part of vendor/autoload.php:

   composer require alleyinteractive/composer-wordpress-autoloader
   

2. Allow the Composer plugin. Composer 2.2+ blocks plugins until you allow them. Either answer the interactive prompt or add:

   "config": {
     "allow-plugins": {
       "alleyinteractive/composer-wordpress-autoloader": true
     }
   }
   

3. Declare your mappings in the root composer.json, mirroring the shape of a normal PSR-4 block but in extra:

   "extra": {
     "wordpress-autoloader": {
       "autoload": {
         "Acme\\Plugin\\": "src/"
       }
     }
   }
   

4. Regenerate the autoloader: composer dump-autoload.
5. First use case: create src/class-my-class.php containing namespace Acme\Plugin; class My_Class {} and reference Acme\Plugin\My_Class — no require statements, and the filename still satisfies WPCS (class-*.php, lowercase, hyphenated).

If you can't (or don't want to) touch the root composer.json — e.g. a mu-plugin bootstrap or a PHPUnit bootstrap — register the loader by hand:

$loader = new \Alley\ComposerWordPressAutoloader\WordPressAutoloader();
$loader->addNamespace( 'Acme\\Plugin', __DIR__ . '/src' );
$loader->register();

Where to look first: the README's Usage section for the exact extra key names, then src/ in the package for WordPressAutoloader (the mapping logic and file-name candidates) and the Composer plugin class (what it hooks into and what it writes under vendor/composer/). Inspecting that generated file is the fastest way to confirm your mappings were picked up.

Implementation Patterns

Per-package config for libraries, root config for the app. Each package can declare its own extra.wordpress-autoloader.autoload block, so a shared internal library ships with WPCS filenames and its consumers get autoloading for free. The root project only declares its own namespaces.

Coexist with PSR-4 rather than migrating everything. Keep autoload.psr-4 for modern code and add the WordPress loader only for legacy WPCS-shaped files. Both loaders can point at src/; only the filename convention differs (see the gotcha about duplicated mappings).

Incremental migration. Move a class from a hand-maintained require_once list into a WPCS-named file, add the namespace prefix mapping once, and new classes autoload with zero further wiring. This is the main day-to-day payoff: you stop editing an includes() bootstrap file for every new class.

Name conversion to keep in your head:

The class name loses its namespace, underscores become hyphens, and everything is lowercased. Because the type prefix can't be inferred from a bare class name, expect the loader to probe class-/interface-/trait- variants — so keep exactly one declaration per file.

Manual loader for tests and unusual entry points. In tests/bootstrap.php, instantiate WordPressAutoloader, add the same namespaces, and register() before loading test fixtures. This decouples tests from whether the Composer plugin ran (useful under --no-plugins CI images).

Legacy global-namespace code. Older WP code with no namespace can be mapped with an empty prefix ("": "includes/"); treat this as a catch-all and prefer converting to a namespace over time.

Build pipeline. Run composer dump-autoload (or a full composer install) as an explicit build step, then smoke-test class resolution. composer install --no-dev is safe as long as the package is a runtime requirement; if you commit a built vendor/ for distribution, include the generated autoload files or your plugin will fatal on activation.

Gotchas and Tips

• The plugin silently doesn't run. --no-plugins, a missing allow-plugins entry, or composer install in an environment with plugins disabled means your mappings are never registered and every class 404s. Symptom: "class not found" even though the file exists and the config looks right. Check composer diagnose and the plugin's output on dump-autoload -v.
• Config edits require a re-dump. Changing extra.wordpress-autoloader.autoload at runtime does nothing until composer dump-autoload regenerates the loader.
• Filename case and hyphenation are load-bearing. WPCS wants class-my-class.php; a file saved as Class-My-Class.php works on macOS and breaks on Linux CI/containers. Same for a stray underscore instead of a hyphen.
• Double mappings cause ambiguous-resolution warnings. If the same namespace appears in both autoload.psr-4 and extra.wordpress-autoloader, an optimized dump may emit "Ambiguous class resolution" and the two loaders will probe the same directory with different filename rules. Pick one per namespace, or accept the redundancy knowingly.
• Optimized/authoritative classmaps. --optimize builds a classmap by parsing files, which usually resolves WPCS-named classes fine, but --classmap-authoritative means Composer's loader won't hit the filesystem at all — make sure the WordPress loader is actually registered (it should be, as a separate spl_autoload_register entry) and verify with a smoke test before shipping.
• Enums, anonymous classes, and function files are edge cases. enum declarations and global function files don't have an obvious WPCS prefix convention; confirm behavior in the source rather than assuming, and keep functions in explicitly required files.
• Debugging snippets:

  var_dump( spl_autoload_functions() );          // is the WP loader registered?
  var_dump( $loader->findFile( 'Acme\Plugin\My_Class' ) ); // what path does it resolve?
  

  Also composer dump-autoload -vvv to watch the plugin run, and COMPOSER_DEBUG_EVENTS=1 to see which events fire.
• Extension points: the WordPressAutoloader instance is a normal object — addNamespace() at runtime lets you register conditional namespaces (e.g. only in admin), and manual instantiation lets you use the package outside Composer entirely. Subclassing it is the cleanest place to add custom filename candidates if your project has a non-standard convention.
• Don't use it as a substitute for a functions loader. It autoloads types only; functions.php-style procedural includes still need explicit require or Composer autoload.files.