Best practices for using Composer in WordPress plugins

[bph]

Discussed in #457

^{Originally posted by nlemoine March 20, 2026}

Summary

More and more WordPress plugin developers use Composer. Two things that don't get much attention yet: autoloader performance and dependency scoping. I'd like to write about both, with actual benchmark data.

Context

WordPress itself doesn't use Composer, but plugin developers do. Over 6,300 plugins on wordpress.org ship a Composer autoloader. That's about 10% of the directory, and it includes the biggest plugins: WooCommerce, Elementor, Yoast SEO, WPForms, Wordfence.

The Developer Blog recently published Implementing Namespaces and Coding Standards in WordPress Plugin Development, which covers PSR-4 autoloading with Composer. A natural follow-up would be what to watch out for when 15+ plugins each register their own spl_autoload handler on every request. A typical PHP application has one Composer autoloader. A typical WordPress site has a dozen or more, and they all try to resolve every class lookup.

Problem 1: autoloader performance

When a plugin runs composer dump-autoload --optimize, Composer generates a classmap of all known classes. Good. But for any class not in the classmap, Composer falls back to PSR-4 filesystem scanning, calling file_exists() for each matching prefix directory. In WordPress, that means every class_exists() call for a class that doesn't exist triggers filesystem lookups across every plugin autoloader with a matching PSR-4 prefix.

And many plugins share the same prefixes because they bundle common libraries (Psr\Log\, Symfony\Polyfill\*, GuzzleHttp\*). More plugins, more overlapping prefixes, more wasted file_exists() calls on every single request.

The fix is one line: composer dump-autoload --classmap-authoritative. Composer then only uses the classmap and returns false immediately for unknown classes. No filesystem fallback.

The numbers

I searched all 63,000+ plugins on wordpress.org using Veloria:

• 6,331 plugins ship a Composer autoloader
• 98% use optimized classmaps (--optimize)
• Only 349 (5.5%) use --classmap-authoritative

That leaves 94.5% that could benefit from a one-line change.

I benchmarked a real WordPress install with 14 popular plugins (Elementor, Yoast, WooCommerce, WPForms, Wordfence, etc.):

Scenario	Response time	Unnecessary file_exists() calls
Without --classmap-authoritative	176 ms	916 per request
With --classmap-authoritative	99 ms	0

44% faster. 916 unnecessary filesystem calls gone. Per request. I will provide a benchmark repository with reproducible scripts.

Problem 2: dependency scoping

Separate problem, same root cause: no isolation between plugins. If Plugin A ships monolog/monolog v2 and Plugin B ships v3, whichever loads first wins. The other may crash.

This already happens in the wild. Popular libraries like Guzzle, Monolog, and Symfony components are bundled by dozens of plugins at different versions.

The article would cover why this happens (WordPress has no dependency isolation, it's just an spl_autoload chain with first-loaded-wins semantics), what tools exist to fix it (PHP-Scoper, Mozart), and the trade-offs (build complexity, larger plugin size, harder debugging).

Proposed article structure

1. Composer in WordPress: growing adoption, why the multi-autoloader architecture is different from standard PHP apps
2. The autoloader problem: profiling data, real numbers
3. The fix: --classmap-authoritative, one line
4. The scoping problem: dependency version conflicts in a shared environment
5. Solutions: PHP-Scoper, Mozart, and practical guidance
6. A checklist for plugin authors shipping Composer

Why now

Composer adoption in plugins is accelerating. The existing Developer Blog article on namespaces and PSR-4 is a great starting point, and this would be a natural companion piece covering the performance and stability side.

I've been submitting PRs to individual plugins (ACF, EWWW Image Optimizer, PublishPress, Yoast SEO) to get them to add --classmap-authoritative. Some merged, some are still open. But fixing plugins one PR at a time doesn't scale to 6,000+. An article on the Developer Blog would reach the entire community at once and turn this into a known best practice instead of something a handful of people discovered on their own.

References

• Composer issue #10205 — Jordi Boggiano (Composer creator): "authoritative autoloading [...] is the best solution I'd say. But that requires every author to get a clue and clean up their act.. Good luck."
• Composer autoloader optimization docs
• Yoast SEO PR #22393 (open)
• ACF PR #962 (merged)
• EWWW Image Optimizer PR #370 (merged)
• PublishPress dev-workspace PR #4 (merged)
• Implementing Namespaces and Coding Standards in WordPress Plugin Development (Developer Blog)
• Veloria (WordPress plugin source code search)
• PHP-Scoper

[bph]

Thank you @nlemoine for the submission! The topic was approved in today's meeting. Thank you for volunteering to write this post! If you comment on this issue, I can assign it to you. (GitHub is funny that way). Or accept the invitation as a Developer Blog Contributor.

[nlemoine]

Thank you @bph for the approval! I accepted the invite. I'll come back to this issue shortly with some more details.

[AntonyXSI]

Thank you both for researching this further and referencing the thread with Jordi. It has been an uphill battle over the years. I think I've only managed to get a handful of plugins to make the switch, but the benchmarking above shows most plugins are using an inefficient autoload method that still needlessly adds to the response time.

It's often a hidden cause of slow TTFB too as it needs multiple plugins or themes sharing composer autoloaders to have an impact which isn't immediately obvious.

Looking forward to the blog post and hoping this will add a bit more traction and awareness to the issue and encourage developers to switch composer to authoritative autoloading.

Perhaps in the future this could be added to a checklist for developers, the plugin check plugin or even potentially the health check plugin/site health?