Wordpress Autoloader Laravel Package

Getting Started

This is a WordPress-side Composer package, not a Laravel one. It solves a single problem: replacing the pile of require_once calls at the top of a plugin with an spl_autoload_register that understands WordPress file naming (class-foo-bar.php → Foo_Bar). If you are a Laravel developer, you reach for it only when you are writing or maintaining WordPress code — a plugin, a theme, or a hybrid app that boots WordPress next to Laravel.

Minimal steps:

1. composer require alleyinteractive/wordpress-autoloader
2. Move your classes into a src/ directory and rename files to WP conventions: class-my-service.php, interface-my-contract.php, trait-my-helper.php.
3. Bootstrap the loader once, after Composer's autoloader is required:

require_once __DIR__ . '/vendor/autoload.php';

$loader = new \Alley\WP\Autoloader\Autoloader( __DIR__ . '/src' );
$loader->register();

Where to look first, in order: the Autoloader class itself (it is small and readable), the README's usage block for the exact constructor/method signatures at your pinned version, and tests/ — the tests are the authoritative spec for how a filename is turned into a class name. Do not assume the mapping rules; read them, because the hyphen/underscore/namespace translation is the entire value proposition and the entire source of bugs.

First real use case: a plugin with 30–60 require_once lines in its main file. Rename, delete the requires, add three lines of bootstrap. That is the 20-minute win that justifies the dependency.

Implementation Patterns

Namespaced plugins. The common pattern is one loader per source root, with the namespace declared so class-foo-bar.php resolves to My\Plugin\Foo_Bar rather than the global Foo_Bar. Confirm the exact registration method name in the README — the surface is deliberately tiny (construct with a root path, register namespaces and classmaps, call register()), and it has changed shape across versions.

Classmap for the stragglers. Legacy files that do not follow conventions (helpers.php, functions-admin.php) go into an explicit classmap rather than being renamed. This lets you migrate incrementally: rename the easy 80%, classmap the rest, delete the classmap entries over time.

One loader, many roots. Instantiate a single loader and register each source directory against it — src/, src/Admin/, src/REST/ — rather than creating four loaders. Multiple loaders work but make duplicate-class debugging harder because precedence depends on registration order.

Lazy loading is the point. Classes are only required when first referenced. Put admin-only classes under src/Admin/ and they cost nothing on front-end requests. This is the same benefit PSR-4 gives you for free in Laravel; here you have to get it by directory discipline.

Hybrid Laravel + WordPress. If you are embedding WordPress inside a Laravel app (wordpress/wp-blog-header.php style), keep the boundary hard: Laravel application code stays PSR-4 in app/, and the autoloader is registered only inside the WordPress bootstrap so the two autoloaders never contend for the same class names. Register it after vendor/autoload.php is required, otherwise Composer's autoloader will not be in the chain when your loader gives up.

Deploy-time classmap. Building the map means scanning the filesystem. Generate it in CI (or on first request behind a persistent cache) rather than on every page load — see gotchas.

Gotchas and Tips

It is not PSR-4, and nothing else will understand it. Composer's autoload block, composer dump-autoload -o, Laravel's container resolution, PHPStan, PHP_CodeSniffer's PSR-4 sniffs, and your IDE's go-to-definition all key off PSR-4. With this loader, class-foo-bar.php declaring Foo_Bar is invisible to every tool except this package at runtime. Expect broken autocomplete and "class not found" static-analysis noise; budget for either a stub composer.json classmap entry (purely for tooling, ignored at runtime) or a phpstan.neon scanFiles/scanDirectories entry.

The filename-to-class-name translation is exact and unforgiving. class-foo-bar.php → Foo_Bar (or Namespace\Foo_Bar). Class_Foo_Bar.php will not load. class-FooBar.php will not load. One class per file — a file named class-helpers.php containing three classes will load exactly one of them and silently fail on the others. When something "does not exist," check the filename before you check anything else.

Case sensitivity bites on macOS. HFS+/APFS is case-insensitive by default, so a mis-cased filename works locally and 500s on Linux production. Add a CI job that runs on Linux. This is the single highest-frequency failure mode for convention-based loaders.

Silent skips. Files that do not match a recognized prefix are ignored with no warning. When a class is missing, dump the generated map (the loader exposes its classmap, or you can var_dump after construction) and confirm the file is even in it. Do that before reaching for xdebug.

Performance on shared hosting. Filesystem scanning per request plus no opcache configured equals measurable overhead. Cache the map to a generated PHP file during deploy and load it back, or at minimum ensure opcache is on with a sane opcache.validate_timestamps setting. Do not benchmark this on your laptop and conclude it is free.

Collision with Composer. If a class name exists in both Composer's map and this loader's map, whichever registered first wins — and spl_autoload_register ordering is easy to get wrong inside WordPress's plugin loading sequence. Register this loader after vendor/autoload.php and keep your WP-facing namespace disjoint from your Laravel namespaces.

The loader must be registered before anything references the classes. In WordPress, that means in the main plugin file or on plugins_loaded at the earliest — not inside init or a hook that runs after another plugin has already tried to touch your classes. Plugin load order is alphabetical, which is a genuinely bad way to discover this.

Adoption risk is real. Ten stars, zero dependents, one maintainer org. The code is small enough to read in an afternoon and small enough to vendor or fork if it is abandoned — but treat it as a dependency you own, not one you assume will be maintained. Pin the version, and if the project is long-lived, consider that the entire feature set is roughly 100 lines of spl_autoload_register plus a filename regex; reimplementing it in-house is a defensible alternative to taking the dependency.

Extension points are minimal by design. There are no WordPress actions or filters fired, so instrumentation means wrapping spl_autoload_register yourself or subclassing the loader. The classmap registration method is the intended escape hatch for anything the conventions cannot express. Use it rather than monkey-patching the convention rules.