Prefix Namespaces in WordPress Plugins to Avoid Conflicts
Ben Word
If you’re bundling Composer dependencies in your WordPress plugin, you need to namespace them. You’re setting up your users for conflicts with other plugins if you don’t implement proper namespacing.
The problem
WordPress has no centralized dependency management. When multiple plugins bundle the same library at different versions, PHP loads whichever one gets registered first. This creates unpredictable race conditions that break plugins.
Conflicts often arise around the psr/log library, which many plugins bundle with the out of the box namespaces from the library.
Doing it wrong
The Acorn compatibility documentation calls out several plugins that are known to bundle conflicting dependencies without proper namespacing:
- WooCommerce PayPal Payments doesn’t prefix
psr/log, resulting in conflicts - WooCommerce UPS Shipping doesn’t prefix
psr/log, resulting in conflicts - WooCommerce USPS Shipping doesn’t prefix
psr/log, resulting in conflicts
These conflicts force WordPress developers to create workarounds and patches when they should be fixing the root cause: unnamespaced dependencies.
The solution
Use PHP-Scoper to prefix all your Composer dependencies with a unique namespace. This isolates your code completely from other plugins.
How Yoast does it right
Yoast SEO is an good example of proper dependency management. They use PHP-Scoper to namespace all their dependencies, including psr/log, preventing the exact conflicts that exist in the WooCommerce plugins mentioned above.
In their repository, you can see their organized PHP-Scoper configuration in config/php-scoper, with separate config files for different dependencies.
This ensures their prefixed YoastSEO_Vendor\Psr\Log namespace never conflicts with other plugins, even those shipping outdated versions of psr/log.
Your responsibility
Plugin developers need to wrap their dependencies with their own namespace to prevent conflicts. It’s not enough to rely on other plugin authors to do the right thing.
Tools like PHP-Scoper exist to solve this problem. Use them.