Composer Fundamentals and WebOps Workflows
Start with Composer basics then explore suggested WebOps workflows for WordPress and Drupal sites on Pantheon.
Discuss in our Forum Discuss in SlackComposer 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.
Dependencies
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. Review Composer require
and require dev
Sections for more information on how these sections are on used on the Pantheon platform.
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 (Latest Version): https://packages.drupal.org/10
- Drupal 7: https://packages.drupal.org/7
Managing Core as a Project Dependency
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.
Build and Deploy Terminology
Build and deploy are terms you'll encounter frequently. Your application goes through a build and deploy process every time you push a change to your repository through Git or activate an environment.
The build process runs before deploy and scans configuration files in your repository and assembles the necessary containers. The build then prepares your application, including:
- Compiling
- Linking
- Uploading artifacts
The deploy process uses the build containers to create an updated version of the live application.
Pull Request Workflow
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:
Scaling Considerations
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.
Custom Upstream Workflow
Use Integrated Composer to preserve the functionality of Pantheon's one-click updates from the Site Dashboard for Composer-managed sites created from a Custom Upstream.
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.
Next Steps
Here are some ways to get started using Composer for your Pantheon sites:
- Create a new Drupal with Integrated Composer site.
- Migrate or upgrade an existing Drupal site to the latest version of Drupal with Integrated Composer.
- Convert a Standard Drupal 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.
Partial Adoption
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 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 is an all or nothing proposition. To use Composer to manage Drupal sites, use the Build Tools or convert an existing Drupal site to Integrated Composer on Pantheon methods.