composer-compatibility-enforcer: The WordPress plugin that rewires Composer’s autoloader

A surgical MU plugin for Bedrock-style stacks that strips conflicted namespaces from plugin loaders so PHP resolves classes from the right vendor tree.

8 min read • View on GitHub • More from unlocnl

A wide library archive with two nearly identical shelves, one marked as the wrong vendor tree and one as the correct one. A hand reaches past the misleading shelf and pulls a red thread toward the right shelf, while a small gate labeled false blocks the wrong path. The scene explains that the plugin redirects class lookup instead of removing packages.
The plugin does not delete the wrong dependency. It tells Composer to stop claiming ownership of it.
Key Takeaways

The bug is not a bad package by itself. It is the first autoloader that wins. In a Bedrock-style WordPress stack, a plugin can ship its own /vendor tree, register a loader early, and shadow the application’s dependency before the correct class ever gets a chance.

That is the problem composer-compatibility-enforcer is built to solve. It does not ask you to rename dependencies, rebuild plugins, or wait for every package maintainer to agree on versions. It changes the rules at runtime so the wrong loader stops pretending it owns a namespace.

The bug is not the package. It is the first autoloader that wins

PHP cannot unload a class once it is loaded, so the only useful move is to change the route before the class is claimed. This repo treats that as a routing problem. If a plugin’s vendor tree is the source of the conflict, the plugin makes that tree invisible to the lookup path for the affected namespaces.

That is why the project matters in modern WordPress infrastructure. Once you combine Composer, Bedrock, and legacy plugin packaging habits, dependency conflicts stop being theoretical and start becoming fatal errors, missing methods, and brittle deployment rules.

What this MU plugin actually changes at runtime

The bridge file hooks into plugins_loaded at priority 11. That is late enough to see the other autoloaders that WordPress plugins have already registered, but early enough to intervene before the request starts instantiating classes in earnest.

add_action('plugins_loaded', function () {
    (new Enforcer())->boot();
}, 11);

Inside the enforcer, the logic scans Composer\Autoload\ClassLoader::getRegisteredLoaders(), finds loaders whose paths start with the targeted plugin vendor directory, and then strips their namespace mappings. The effect is narrow. Only the chosen plugin tree gets edited.

Composer does not need to be rebuilt. The plugin edits loader ownership so the lookup falls through to the right tree.

A close-up of a Composer class map ledger on a desk, with one namespace erased from the PSR-4 column and a small tab labeled false pinned beside a class entry. A search beam passes over the wrong shelf and continues to the next shelf in the background. The image explains how the plugin makes one loader stop claiming a class so another loader can win.
The key trick is not destruction. It is denial of ownership inside the class map.

The real trick: Composer can be told a class is not there

This is the centerpiece. The plugin removes namespace mappings with setPsr4($namespace, []), then reaches into Composer’s protected $classMap with Reflection and edits it directly. When a class is marked false, Composer treats that loader as if the class does not belong to it.

$loader->setPsr4($namespace, []);

$ref = new ReflectionObject($loader);
$prop = $ref->getProperty('classMap');
$prop->setAccessible(true);
$classMap = $prop->getValue($loader);
$classMap[$class] = false;
$prop->setValue($loader, $classMap);

That detail is the whole story. The plugin does not unload the wrong class. It makes the wrong loader stop answering the question. PHP keeps walking until it finds the correct class in the global application tree.

This is elegant because it turns a runtime conflict into a deterministic routing decision. It is also fragile in the way all Reflection-based tools are fragile. Composer internals have to stay close enough for this to work.

Why the plugin is opinionated about doing nothing by default

The repo’s zero-default stance is the right kind of boring. Nothing is blocked until a project explicitly configures the rules through composer_compatibility_enforcer_rules. That keeps the package from guessing which dependencies are safe to touch.

That is not just defensive design. It is a statement about ownership. Compatibility policy belongs in the application, not hidden inside the plugin. For teams with multiple environments, that matters more than a clever default ever would.

What it replaces, and what it does not

ToolWhen it actsWhat it changesMain benefitMain limitation
composer-compatibility-enforcerAt runtime after loaders registerAutoloader ownership for selected namespacesForces class resolution to fall through to the correct vendor treeDepends on Composer internals and Reflection
MozartDuring build or packagingNamespaces bundled dependenciesPrevents collisions by isolating librariesAdds namespacing overhead and rebuild steps
ComposerRequireCheckerBefore deployment, in CIDependency declaration correctnessCatches missing direct requirementsDoes not fix runtime shadowing
Vanilla Composer validationBefore install or releasecomposer.json and constraint healthConfirms metadata is structurally validCannot repair an already conflicting loader

The comparison is simple once you see it. Mozart renames the dependency. ComposerRequireChecker verifies the dependency. Composer validates the manifest. This plugin intervenes later and changes which tree gets to answer the class lookup.

Why this is a WordPress problem disguised as a Composer problem

Modern WordPress makes old assumptions collide with new packaging. Plugins still ship bundled dependencies. Applications increasingly want a single shared dependency tree. Bedrock and Acorn-style stacks make that collision visible because they bring Composer discipline into an ecosystem that was never designed for it.

That is why this repo feels so specific. It is not a general PHP framework tool. It is a narrow fix for the weird middle ground where WordPress plugin habits meet application-level dependency management.

The trade-off: power through reflection, fragility through internals

The upside is precision. The downside is a maintenance contract with Composer’s private shape. If the loader internals change, the trick may need updates. That is acceptable for an infrastructure knife, but it is not the kind of code you want pretending to be a permanent platform primitive.

The project is strongest when used as a targeted compatibility layer for a known stack, not as a universal patch for every PHP application on earth.