WordPress Development

Using Composer with WordPress: Dependencies, Plugins and Autoloading

Using Composer with WordPress: Dependencies, Plugins and Autoloading

For years, WordPress sites were managed by uploading files: download a plugin zip, upload it, update it from the dashboard. That works, but it makes it hard to know exactly which versions are running, to reproduce a site reliably on another server or to use modern PHP libraries in your own code.

Composer, PHP’s dependency manager, solves these problems. It lets you declare exactly which plugins, themes and libraries a project needs, install them consistently on any machine and load your own classes automatically. Many professional WordPress teams use Composer as the backbone of their workflow.

It’s not necessary for every site, but if you build custom plugins, work in a team or manage sites through version control and deployments, it’s worth understanding. Here’s how to use Composer with WordPress.

What Composer does

Composer reads a composer.json file describing your project’s dependencies, downloads them into the project and records the exact installed versions in composer.lock. Anyone running composer install gets exactly the same versions.

It also generates an autoloader, so PHP classes load automatically when used, without long lists of require statements.

Two main uses in WordPress

  1. Managing a whole site: WordPress core, plugins and themes declared as dependencies.
  2. Building plugins and themes: using third-party PHP libraries and autoloading your own classes.

Managing a site with Composer

WPackagist

WPackagist mirrors the WordPress.org plugin and theme directories as Composer packages. Add it as a repository, then require plugins by name:

The installer-paths setting, handled by the composer/installers package, tells Composer where WordPress expects plugins and themes.

Run composer install, and the plugins appear in the right folders.

WordPress core

WordPress core can also be installed through Composer using community-maintained packages, often into a subdirectory, with wp-content kept separately. This keeps core cleanly separated from your own code.

Project structures like Bedrock

Bedrock is a popular WordPress project structure built around Composer. It separates core, configuration and content, uses environment variables for configuration and manages everything through Composer. It’s a good starting point if you want a fully Composer-driven setup, with a learning curve for teams used to traditional WordPress structures.

Premium plugins

Premium plugins aren’t on WPackagist. Options include:

  • Vendors that provide their own Composer repositories with licence authentication.
  • Private Composer repositories you host for licensed plugins.
  • Committing premium plugins to your repository where licences allow.

Never commit licence keys or credentials to a public repository. Use Composer’s authentication configuration or environment variables.

Updates with Composer

Instead of clicking update in the dashboard, you update through Composer:

Then commit the updated composer.lock, test on staging and deploy. Every update is tracked and reproducible.

Disable dashboard plugin installation and updates on Composer-managed sites, with DISALLOW_FILE_MODS, to prevent differences between production and your repository. Make sure someone is responsible for running updates, because the dashboard will no longer do it.

Composer in plugins and themes

Autoloading your classes

Composer’s PSR-4 autoloading maps a namespace to a folder:

A class MySiteToolsReading_Time would live in src/Reading_Time.php. In your main plugin file:

No more require statements for every file. After adding new classes, autoloading just works; after changing autoload configuration, run composer dump-autoload.

Using third-party libraries

Composer makes it easy to use libraries, like an HTTP client, a PDF generator or a payment SDK, in your plugin:

The dependency conflict problem

Here’s an important pitfall. All plugins on a WordPress site share the same PHP environment. If two plugins include different versions of the same library, PHP loads whichever is loaded first, and the other plugin may break with confusing errors.

For site-specific plugins on sites you control, this risk is manageable. For plugins distributed to many sites, it’s a real problem. Solutions include:

  • Prefixing dependencies: tools like Strauss or PHP-Scoper rewrite the namespaces of bundled libraries to unique names, so your copy can’t conflict with another plugin’s copy.
  • Keeping dependencies minimal: avoid adding a large library for something you could write in a few lines.

Shipping vendor files

WordPress plugins installed from zip files don’t run Composer. If your plugin uses Composer dependencies, include the vendor folder, or the necessary files, in the distributed plugin. Run composer install with –no-dev and –optimize-autoloader when building releases, so development tools aren’t included and autoloading is fast.

For plugins on WordPress.org, include the vendor folder in the release, but make sure it contains only the production dependencies you need.

Development dependencies

Composer distinguishes between production dependencies and development dependencies, which are only needed during development:

Development tools, like PHPUnit, coding standards and static analysis, stay out of production builds when you install with –no-dev.

Composer scripts

Composer can run scripts, which is handy for common tasks:

Run them with composer test or composer lint.

Deployment workflows

A Composer-based deployment usually looks like:

  1. Code, composer.json and composer.lock are committed to the repository.
  2. The deployment process, often in CI, runs composer install –no-dev –optimize-autoloader.
  3. The built files are deployed to the server.

Don’t commit the vendor folder for site projects when your deployment runs Composer; do commit composer.lock, which guarantees consistent versions.

Avoid running composer update on production servers. Update locally or in CI, test, then deploy the updated lock file.

Security considerations

  • Keep dependencies updated, as libraries have vulnerabilities too.
  • Use tools that check composer.lock against vulnerability databases. Composer itself can audit dependencies with composer audit.
  • Only use well-maintained, reputable packages.
  • Protect credentials for private repositories.

When Composer isn’t worth it

For a small brochure site managed by a non-technical owner who updates plugins from the dashboard, Composer adds complexity without much benefit. It shines for developer-managed sites with version control, staging and automated deployments, and for custom plugins with dependencies.

A practical adoption path

Teams new to Composer don’t need to convert everything at once. A sensible path:

  1. Start in your custom plugins. Add a composer.json for autoloading your own classes and development tools like PHPUnit and coding standards. This is low risk and immediately useful.
  2. Add libraries carefully. When a plugin genuinely benefits from a third-party library, add it through Composer, and prefix it if the plugin is distributed.
  3. Manage site plugins through Composer on one project with a solid deployment workflow. Learn how updates, testing and deployments feel in practice.
  4. Standardise across projects once the workflow is proven, perhaps with a starter structure like Bedrock or your own template.

Each step delivers value on its own, so you can stop wherever the benefits stop outweighing the effort.

Lock files and teamwork

The composer.lock file is what makes Composer reliable for teams. When one developer updates dependencies and commits the lock file, everyone else and every deployment installs exactly the same versions. Conflicts in composer.lock during merges are common; resolve them by re-running composer update for the affected packages rather than editing the file by hand.

Keep an eye on PHP version requirements

Libraries declare which PHP versions they support. Set the platform PHP version in composer.json to match your production server, so Composer doesn’t install a library version that requires a newer PHP than production has:

This prevents the frustrating situation where everything works locally on a newer PHP version but fails after deployment.

Common Composer mistakes

  • Running composer update on production instead of composer install from a tested lock file.
  • Forgetting to commit composer.lock, so environments install different versions.
  • Shipping development dependencies in production builds.
  • Bundling unprefixed libraries in distributed plugins, causing conflicts on users’ sites.
  • Leaving private repository credentials in committed files.

Avoiding these covers most of the problems teams run into when adopting Composer.

Audit dependencies regularly

Run composer audit as part of your routine maintenance or CI pipeline. It reports known vulnerabilities in installed packages, so you can update before they become a problem on production sites.

Small, regular dependency updates are far safer than rare, large ones.

Frequently asked questions

Do I need Composer to build WordPress plugins?

No. Many plugins don’t use it. It’s helpful for autoloading and third-party libraries.

What’s WPackagist?

A Composer repository mirroring WordPress.org plugins and themes, so you can install them with Composer.

Why do Composer libraries conflict between plugins?

All plugins share one PHP environment. Two plugins bundling different versions of the same library can clash. Prefixing dependencies avoids this.

Should I commit the vendor folder?

For sites deployed with Composer, commit composer.lock but not vendor. For distributed plugins, include production vendor files in release packages.

Final thoughts

Composer brings order to WordPress projects: reproducible plugin and theme versions, clean autoloading and access to the wider PHP ecosystem. Use WPackagist and installer paths to manage sites, PSR-4 autoloading in your plugins, prefix bundled libraries in distributed plugins to avoid conflicts, keep development tools out of production and deploy from a committed lock file. Adopt it where it helps, and your projects become more predictable and easier to maintain.