Drupal 8 Composer Best Practices

Whether you are familiar with Composer or not, using it to manage dependencies on a Drupal project entails its own unique set of best practices. In this article, we will start by getting a Composer-managed Drupal project set up, and highlight some common questions and issues you may have along the way.

Before we dive in, though, you may be asking yourself, “Why Composer? Can’t I just download Drupal and the modules I need without requiring another tool?” Yes you can, but you will quickly realize it’s not a simple task:

1. Contributed modules or themes often depend on third-party libraries installed via Composer. Without using Composer for the project, you’ll need to manage these individually when downloading, which can be quite a chore.
2. Some packages and modules only work with certain versions of PHP or Drupal. While Drupal core does help you identify these issues for modules and themes, it’s still a manual process that you’ll need to work through when choosing which versions to download.
3. Some packages and modules conflict with other packages. You’ll need to read the composer.json files to find out which.
4. When you upgrade a package or a version of PHP, you’ll need to do all the above over again.
5. If you’re thinking you’ll use drush dl and friends, they’ve been removed in favor of Composer.

Dependency management is complicated, and it’s not going to get any easier. As Ryan Szrama put it , “if you’re not using a dependency manager [like Composer], then you’re the dependency manager, and you are unreliable.”

Where do I start?

To begin, it’s good to familiarize yourself with the fantastic documentation on Drupal.org . If you haven’t already, install Composer in your development environment. When getting started, it’s extremely important that your development environment is using the same version of PHP that the target production environment will use. Otherwise Composer may download packages that won’t work in production. (With larger development teams, using something like Vagrant or Docker for local development can help ensure compatibility between local development instances and the production stack, but that’s a separate topic).

To start with, you need to get Drupal core installed. If you are familiar with using starter-kits like Drupal Boilerplate in Drupal 7, there is a Composer template for Drupal projects called, well, drupal-project. It’s the recommended starting place for a Composer-based Drupal 8 installation. Before you create it—again—be sure you are using the production version of PHP. Once you’ve confirmed that, run:

$ composer create-project drupal-composer/drupal-project:8.x-dev \
example --stability dev --no-interaction

This will copy the drupal-project to the example directory, and download Drupal core and some handy packages. This is a good point to cd into the example directory, run git init , and to then create your initial commit for your project.

This also might be a good time to pop open the composer.json file that was created in there (which should look a lot like this). This file serves as your “recipe” for the project.

How do I download modules and themes?

If you are familiar with using drush dl in Drupal 7 to download contributed modules and themes, it can be a bit of a shift switching to a Composer workflow. There is a different syntax for selecting the version you’d like, and in some cases it’s best to not commit the actual downloaded files to your repository (more on that to follow).

For most instances, you can use composer require [vendor]/[packagename] to grab the package you’d like. Most Drupal modules and themes are hosted on a custom Composer repository, which drupal-project configures for us out of the box. That means we can use drupal as the vendor to download Drupal modules and themes that are maintained on drupal.org. If you aren’t using drupal-project, you may need to add the Drupal.org Composer repository yourself.

For example, if you were wanting to download the Devel module, you would run the following command:

$ composer require drupal/devel

For most cases, that would download the most recent stable version of the Devel module that is compatible with your version of Drupal and PHP. If you used drupal-project above, it would download the module to web/modules/contrib. If you want to change the download destination, you can alter the paths in your composer.json. Look for the installer-paths under extra and adjust to your liking.

Development Dependencies

The Devel module is a good example to use, as it brings up a few other things to note. For example, since the Devel module shouldn’t be used in a production environment, you may only want it to get downloaded on development environments. With Composer, you can achieve this by passing the --dev flag to the composer require command.

$ composer require --dev drupal/devel

This will ensure that the Devel module is available for your developers when they run composer install , but that it won’t ship with your production release (which should get built using composer install --no-dev ). This is just an example, and your project needs may differ, but the use of --dev to specify dependencies only needed during development is a recommended best practice.

As a side note, if you are committing your exported Drupal 8 configuration to code, you may want to use the Configuration Split module to ensure that the Devel module’s enabled status doesn’t get pushed to production by mistake in a release.

Nested Dependencies

Another thing to note is that the Devel module ships with its own composer.json file. Since we used Composer to download Devel, Composer will also read in Devel’s composer.json and download any dependencies that it may have. In this case (at the time of this writing), Devel doesn’t have any required dependencies, but if you were to use Composer to download, say Address module, it would pull in its additional dependencies as well, as Address module uses Composer to specify some additional dependencies .

Downloading specific versions

While it’s most often fine to omit declaring a specific version like we did above, there still may come a time when you need to narrow the range of possibilities a bit to get a package version that is compatible with your application.

Judging by the length of the Composer documentation on Versions and constraints, this is no small topic, and you should definitely read through that page to familiarize yourself with it. For most cases, you’ll want to use the caret constraint (e.g., composer require drupal/foo:^1.0 means the latest release in the 8.1 branch), but here’s some more details about versions and constraints:

1. Read up on Semantic Versioning if you aren’t familiar with it. Basically, versions are in the x.y.z format, sometimes described as MAJOR.MINOR.PATCH , or BREAKING.FEATURE.FIX . Fixes increment the last number, new features increment the middle number, and refactors or rewrites that would break existing implementations increment the first number.
2. Use a colon after the vendor/package name to specify a version or constraint, e.g. composer require drupal/foo:1.2.3 (which would require that exact version (1.2.3) of the foo package). If you’re used to drush syntax (8.x-1.2.3), the Composer syntax does not include the Drupal version (i.e., there's no 8.x).
3. Don’t specify an exact version unless you have to. It’s better to use a constraint.
4. The caret constraint (^): this will allow any new versions except BREAKING ones—in other words, the first number in the version cannot increase, but the others can. drupal/foo:^1.0 would allow anything greater than or equal to 1.0 but less than 2.0.x . If you need to specify a version, this is the recommended method.
5. The tilde constraint (~): this is a bit more restrictive than the caret constraint. It means composer can download a higher version of the last digit specified only. For example, drupal/foo:~1.2 will allow anything greater than or equal to version 1.2 (i.e., 1.2.0, 1.3.0, 1.4.0,…,1.999.999), but it won’t allow that first 1 to increment to a 2.x release. Likewise, drupal/foo:~1.2.3 will allow anything from 1.2.3 to 1.2.999, but not 1.3.0.
6. The other constraints are a little more self-explanatory. You can specify a version range with operators, a specific stability level (e.g., -stable or -dev ), or even specify wildcards with *.

What do I commit?

Now that we’ve got a project started using Composer, the next question you may have is, “What files should I commit to my repository?” The drupal-project will actually ship a default .gitignore file that will handle most of this for you. That said, there are a few things that may be of interest to you.

You may have noticed that after running some of the above commands, Composer created a composer.lock file in your repository. The composer.lock file is a very important file that you want to commit to your repository anytime it changes. When you require a new package, you may have omitted a version or a version constraint, but Composer downloaded a specific version. That exact version is recorded in the composer.lock file, and by committing it to your repository, you then ensure that anytime composer install is run on any other environment, the same exact code gets downloaded. That is very important from a project stability standpoint, as otherwise, Composer will download whatever new stable version is around based on what’s in composer.json.

Now that we understand more about what composer.lock is for, here’s a list of what to commit and what not to commit:

1. Commit composer.json and composer.lock anytime they change.
2. There’s no need to commit anything in ./vendor , Drupal core (./web/core), or contributed modules and themes (./web/modules/contrib or ./web/themes/contrib). In fact, it’s recommended not to, as that ensures the same code is used on all environments, and reduces the size of diffs. If you really want to (because of how your code gets deployed to production, for example), it is possible, you’ll just need to change the .gitignore, and always make sure the committed versions match the versions in composer.lock.
3. Commit any other custom code and configuration as usual.

How do I keep things up to date?

Updating modules, themes, and libraries downloaded with Composer is similar to installing them. While you can run composer update to update all installed packages, it’s best to save that for the beginning of a sprint, and update individual projects as needed after that. This ensures you only update exactly what you need without risking introducing bugs from upstream dependencies. If you aren’t working in sprints, set up a regular time (weekly or monthly) to run composer update on the whole project.

To update the Devel module we installed earlier, you could run:

$ composer update --with-dependencies drupal/devel

You might be wondering what that --with-dependencies option is. If you run the update command without it, composer will update just the module, and not any packages required by that module. In most circumstances, it’s best to update the module’s dependencies as well, so get used to using --with-dependencies.

You can also update multiple packages separated by spaces:

$ composer update --with-dependencies drupal/foo drupal/bar

For a more aggressive approach, you can also use wildcards. For example, to update all drupal packages, you could run:

$ composer update --with-dependencies drupal/*

Once complete, be sure to commit the changes to composer.lock.

What about patches?

Inevitably, you’ll need to apply some patches to a Drupal module, theme, or possibly Drupal core. Since you aren’t committing the actual patched modules or themes with a Composer workflow, you’ll need some way to apply those patches consistently across all environments when they are downloaded. For this we recommend composer-patches. It uses a self-documenting syntax in composer.json to declare your patches. If you’re using drupal-project mentioned above, composer-patches will already be installed and ready to use. If not, adding it to your project is as simple as:

$ composer require cweagans/composer-patches

While it’s installing, take this time to go read the README.md on GitHub.

Once installed, you can patch a package by editing your composer.json . Continuing with our example of Devel module, let’s say you wanted to patch Devel with a patch from this issue. First step?—copy the path to the patch file you want to use. At the time of this writing, the most recent patch is https://www.drupal.org/files/issues/2860796-2.patch .

Once you have the path to the patch, add the patch to the extras section of your composer.json like so:

"extra": {
  "patches": {
    "drupal/devel": {
      "2860796: Create a branch of devel compatible with Media in core": "https://www.drupal.org/files/issues/2860796-2.patch"
    }
  }
} 

You can see that in the above example, we used the node id (2860796) and title of the Drupal.org issue as the key, but you may decide to also include the full URL to the issue and comment. It’s unfortunately not the easiest syntax to read, but it works. Consistency is key, so settle on a preferred format and stick to it.

Once the above has been added to composer.json, simply run composer update drupal/devel for the patch to get applied.

$ composer update drupal/devel
Gathering patches for root package.
Removing package drupal/devel so that it can be re-installed and re-patched.
Deleting web/modules/contrib/devel - deleted
> DrupalProject\composer\ScriptHandler::checkComposerVersion
Loading composer repositories with package information
Updating dependencies (including require-dev)
Package operations: 1 install, 0 updates, 0 removals
Gathering patches for root package.
Gathering patches for dependencies. This might take a minute.
- Installing drupal/devel (1.2.0): Loading from cache
- Applying patches for drupal/devel
https://www.drupal.org/files/issues/2860796-2.patch (2860796: Create a branch of devel compatible with Media in core)

And finally, commit the changes to both composer.json and composer.lock .

If any of your dependencies declare patches (for example, let’s say a module requires a patch to Drupal core to work properly), you’ll need to explicitly allow that in your composer.json. Here’s a quick one-liner for that:

$ composer config extra.enable-patching true

How do I remove a module or theme?

Removing a module or theme using Composer is fairly straightforward. We can use composer remove for this:

$ composer remove drupal/devel

If you added drupal/devel with the --dev flag, you might get a prompt to confirm the removal from require-dev . If you want to avoid that prompt, you can use the --dev flag in your remove command as well:

$ composer remove --dev drupal/devel

Once it’s done, commit your composer.json and composer.lock file.

Anything else to watch out for?

Removing patches

If you need to remove a module or theme that has patches, the patches don’t automatically get removed from the composer.json file. You can either remove them by hand in your editor, or run:

$ composer config --unset extra.patches.drupal/devel

Lock hash warnings

On a related note, any time you manually edit composer.json in this way without a subsequent composer update, the hash in composer.lock will be out of date, throwing warnings. To fix that without changing the code you have installed, run composer update --lock. That will just update the hash in the lock file without updating anything else. Once complete, commit the composer.json and composer.lock.

PHP Versions…again

As mentioned early on, it’s very important with a Composer-based workflow that the various environments use the same major and minor release of PHP. If you aren’t using Vagrant or Docker for local development and are finding it difficult to standardize, you can enforce a specific PHP version for Composer to adhere to in composer.json.

$ composer config platform.php 7.1

Once added, don’t forget to update your lock file and commit the resulting composer.json and composer.lock .

$ composer update --lock

Speeding things up

There are some Composer operations that can be slow. To speed things up, you can install Prestissimo, which will allow Composer to run operations in parallel. It’s best to do this globally:

$ composer global require hirak/prestissimo

It’s not perfect

You will inevitably run into some frustrating issues with a Composer workflow that will cause you to question its wisdom. While there may be scenarios where it might make sense to abandon it for other options, you will bear the burden of managing the complexities of your project’s dependencies yourself. If you stick with Composer, the good news for you is that you are not alone, and these issues promise to improve over time because of that. Think of it as an investment in the long-term stability of your project.

Collage of JoAnn Falletta by Mark Dellas.