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.
- This plugin solves dependency shadowing by changing which Composer loader gets to claim a class, not by removing packages from memory.
- Its core move is runtime surgery on Composer internals, including namespace stripping and a class-map entry set to false.
- The design is deliberately opt-in, which keeps compatibility policy in project config instead of hiding it inside a global default.
- Compared with namespace-wrapping or static checks, it intervenes later and targets the exact failure mode that breaks Bedrock-style WordPress stacks.
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.
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
| Tool | When it acts | What it changes | Main benefit | Main limitation |
|---|---|---|---|---|
| composer-compatibility-enforcer | At runtime after loaders register | Autoloader ownership for selected namespaces | Forces class resolution to fall through to the correct vendor tree | Depends on Composer internals and Reflection |
| Mozart | During build or packaging | Namespaces bundled dependencies | Prevents collisions by isolating libraries | Adds namespacing overhead and rebuild steps |
| ComposerRequireChecker | Before deployment, in CI | Dependency declaration correctness | Catches missing direct requirements | Does not fix runtime shadowing |
| Vanilla Composer validation | Before install or release | composer.json and constraint health | Confirms metadata is structurally valid | Cannot 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.





