Composer is a widely-used PHP dependency and package manager that provides an alternative, more modern way to manage the external (non-core) code used by a WordPress or Drupal site.
At its primary level, Composer needs:
- A list of dependencies
- A place to put the dependencies
Understanding how Composer can be used independent of Drupal or WordPress is a good place to learn more about the general concepts. For a summary of basic usage, see Composer's own documentation.
Composer encourages a mental model where code not written specifically for a given project is a dependency. Only files unique to the project are tracked as part of the project's main source repository, also referred to as the canonical site repository. Dependencies for WordPress and Drupal include core, plugins, contrib modules, themes, and libraries. A single dependency, such as a theme, is referred to as a package.
Composer looks within The PHP Package Repository for dependencies to install, which does not include Drupal or WordPress packages by default. Additional repositories must be configured for Composer to use packages not found in the default repository. Each framework provides its own respective package repository so dependencies can be managed with Composer:
- WordPress: https://wpackagist.org
- Drupal 9: https://packages.drupal.org/9
- Drupal 7: https://packages.drupal.org/7
Sites managed with Composer should use the nested docroot feature, which allows core to be installed within the
web subdirectory instead of the default root directory of the site's codebase. A nested docroot is the simplest path towards reliable core updates in a Composer workflow.
This is possible on Pantheon by specifying
web_docroot: true in
pantheon.yml file. For details, see Serving Sites from the Web Subdirectory.
In this WebOps workflow, a Multidev environment is created on Pantheon for each pull request branch on GitHub. Work in these environments can also be committed back to the same branch for review on GitHub. When a pull request is merged into the default branch on GitHub, the result is deployed to the Dev environment on Pantheon:
We recommend the Pull Request workflow for single site use cases, and for most use cases involving larger site portfolios such as EDUs. You can create a "template" repository based off Pantheon's example repositories and customize it to your liking, then use the template to create new sites.
However, this method does not support one-click updates in the Site Dashboard. Adopting this WebOps workflow means forgoing all other update techniques in favor of Composer. If your use case requires a simpler update strategy for non-technical site admins, this workflow could present problems scaling, or at the very least require additional training for your development team.
To maintain a Composer-based workflow with one-click updates through the Dashboard, consider using Integrated Composer.
Updates made using Integrated Composer are only committed at the Custom Upstream level by a single repository maintainer. Updates then trickle down to sites created from the Custom Upstream as one-click updates in the Pantheon Site Dashboard. Custom Upstreams using Integrated Composer with dependencies in
upstream-configuration/composer.json can have their own site-specific dependencies added in the top-level
composer.json file. Custom Upstreams using Integrated Composer should avoid changing the top-level
composer.json file after sites have been created from the Custom Upstream to avoid merge conflicts.
If you are not using Integrated Composer to update your Custom Upstream, all dependencies must be committed.
A shortcoming of the Custom Upstream workflow is that site-specific dependencies are likely to cause a lot of conflicts. This workflow is most practical for a large group of sites that require a single set of dependencies. You should only use this workflow if you don’t intend to use site-specific themes, modules, or plugins downstream.
You can also prevent upstream updates by setting an empty upstream.
Here are some ways to get started using Composer for your Pantheon sites:
- Create a new Drupal 9 with Integrated Composer site.
- Migrate or upgrade an existing Drupal 8 or 9 site to Drupal 9 with Integrated Composer.
- Convert a Standard Drupal 8 Site to a Composer Managed Site.
- Follow the Build Tools Guide to learn best practices for Composer-managed sites with continuous integration (CI) workflows.
- Create a new WordPress with Integrated Composer site.
If you're not ready to go all in with a Composer workflow and you want to see how it works on a smaller scale, follow the Manage Some Dependencies with Composer guide to get started.
Partial Composer adoption for Drupal 8 sites is not supported since Composer is used by core, meaning any change to
composer.json or the
vendor directory would result in massive merge conflicts when trying to update core via one-click updates in the Pantheon Site Dashboard. Composer with Drupal 8 is an all or nothing proposition. To use Composer to manage Drupal 8 sites, use the Build Tools or convert an existing Drupal 8 site to Integrated Composer on Pantheon methods.