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 Slack

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.

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:

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:

Multidev PR workflow

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:

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.

More Resources