Using Composer with Drupal

Last updated on
3 May 2017

Background

Composer is a dependency manager for PHP. Drupal core uses Composer to manage core dependencies like Symfony components and Guzzle.

There are many benefits to using Composer. In short, it allows us to systematically manage a sprawling list of dependencies (and their subsidiary dependencies). It assists with locating, downloading, validating, and loading said packages, all while ensuring that exactly the right versions for each package are used. It can be a pain, but it's far better than using either nothing or developing a home-brewed solution.

Composer in Drupal core

Drupal's composer-built dependencies are not committed (via git) to Drupal core's repository. This is why you will not find a "vendor" directory in the core repository. Instead, composer.json and composer.lock are committed to Drupal core. These files act as a manifest for building dependencies.

Drupal.org builds Drupal core's composer-defined dependencies and packages them (along with Drupal itself) into the .zip and .tar.gz archives that are available for download on Drupal.org. So, if you've downloaded Drupal as a .tar.gz or .zip file from Drupal.org, or if you've used Drush to download Drupal, then the Composer dependencies for Drupal core have already been built and provided to you.

If you'd like to manage additional dependencies via Composer (beyond the dependencies already required by Drupal core) then continue reading.

Using Composer to manage Drupal dependencies

There are a few scenarios in which you might use Composer on a Drupal project.

  1. As a Drupal site architect, I'd like to manage dependencies for an entire Drupal site via Composer. For example, I want to install and update Drupal, itself, via Composer, along with any necessary non-core modules, themes, and third party libraries for the entire Drupal site.
  2. As a Drupal developer, I'd like to manage contributed dependencies for a custom project (module or theme) via Composer.
  3. As a maintainer of a contributed Drupal project, I'd like to manage contributed dependencies via Composer.
    • If a contributed project maintainer wishes to add a dependency on a Packagist library that is not hosted on drupal.org, they can add a composer.json file to their contributed project. Most contrib developers do not need to do this as long as their drupal.org dependencies are expressed in their info.yml files.

See also: