Using Composer to manage Drupal site dependencies

Last updated on
1 February 2018

Composer can be used to download Drupal, Drupal contributed projects (modules, themes, etc.) and all of their respective dependencies. These instructions vary based on your approach to managing your Drupal installation.

Content of this page

Installing Composer

You need Composer to be installed on your local machine before executing any Composer commands. Please see Getting Started on getcomposer.org to install Composer itself.

Download Drupal core using Composer

Composer can be used to download Drupal core. There are multiple options that can be used. Comparison table can be found below.

Option A: drupal-composer/drupal-project

  • This open source project acts as a kickstarter for Composer-based Drupal sites.
  • It provides default configuration that otherwise needs to be added manually.
  • Support and development of this open source project takes place at https://github.com/drupal-composer/drupal-project/issues

Option B: drupal/drupal

  • This uses Drupal itself as a template for the new site.
  • It is the simplest solution but lacks additional configuration that can be helpful.
  • The biggest pitfall of this approach is related to scaffold files, see below.
  • The Drupal core can't be updated with composer update like extensions.

Option C: hussainweb/drupal-composer-init

  • This open source project provides a composer command to create a composer.json for a Drupal 7/8 site.
  • The generated composer.json is very similar to the drupal-composer/drupal-project template and includes all its features with a smaller and easier to edit composer.json.
  • Support and development of this open source project takes place at https://github.com/hussainweb/drupal-composer-init/issues.

Comparison of the options

option A option B option C
feature drupal-composer/drupal-project drupal/drupal ^8.3.0 hussainweb/drupal-composer-init
open source yes yes yes
directory structure web is subdir docroot is repo root web is subdir by default
installer-paths config yes yes automatically handled, overridable
repositories config yes yes yes
updates scaffold files yes no yes
includes drush yes no yes
includes drupal console yes no yes

Scaffold files

  • Scaffold files are files that belong to Drupal but are not in the "core" subdirectory (.htaccess, robots.txt, index.php, update.php, etc.)
  • If you use drupal/drupal (Option B) as the template for your new Composer project, there will be no Composer-based mechanism for updating scaffold files during a core update. 
  • drupal-composer/drupal-project (Option A) manages scaffold files for you by using drupal-composer/drupal-scaffold.

Option A: drupal-composer/drupal-project

  • Run composer create-project drupal-composer/drupal-project:8.x-dev my_site_name_dir --stability dev --no-interaction
  • This will download the 'drupal-composer/drupal-project' project into a folder named 'my_site_name_dir'
  • It also automatically executes composer install which will download Drupal 8 and all its dependencies. 

You might want to modify some of the properties of the downloaded composer.json before running composer install. For example, it is possible that you want to rename the subdirectory 'web' to something else.

  • Run git clone https://github.com/drupal-composer/drupal-project.git my_site_name_dir
  • You can go to my_site_name_dir and edit the composer.json file.
  • Run composer install. This will download Drupal 8 and all its dependencies. 

Follow the instructions for drupal-composer/drupal-project to learn more about it's configuration and features.

Option B: drupal/drupal

  • Run composer create-project drupal/drupal my_site_name_dir
  • This will download the 'drupal/drupal' project into a folder named 'my_site_name_dir'
  • It also automatically executes composer install which will download Drupal 8 and all its dependencies.

If you want to download contributed modules or themes using Composer, you need to first add drupal.org as a composer repository. See instructions below.

Option C: hussainweb/drupal-composer-init

You will first need to download and install the 'drupal-composer-init'.

  • Run composer global require hussainweb/drupal-composer-init

To generate a new composer.json file for Drupal 8:

  • Run composer drupal-init
  • Follow the instructions on the screen
  • Demo 

To generate a composer.json for Drupal 7 site:

  • Run composer drupal-init --drupal-7
  • Follow the instructions on the screen
  • Demo

Once the composer.json has been created

  • Run composer install
  • This will download Drupal and all the required dependencies for you

Note for git-cloned drupal/drupal

If you downloaded the latest development version of Drupal using git, you will need to download all the third party components that Drupal 8 has listed in its composer.json.

  • Run composer installinside of the repository directory. 
  • This will download Drupal's composer dependencies into the 'vendor' directory.

If you want to download contributed modules or themes using Composer, you need to first add drupal.org as a composer repository. See instructions below.

Download contributed modules, themes and their dependencies using Composer

It is increasingly common that contributed Drupal modules have dependencies to third party libraries. Some of these modules can only be installed using Composer. If you downloaded Drupal 8 core using Composer, you most probably want to use Composer to download all modules and themes using Composer.

This chapter has the following sub-sections:

Download contributed modules and themes using Composer

These instructions will work for you without any additional configurations if you downloaded Drupal 8 core using 'drupal-composer/drupal-project' (Option A above) or 'hussainweb/drupal-composer-init' (Option C above) or if you're using Drupal 8.3.0 or later. In other cases, you may need to define drupal.org as a composer repository and define the directories where Drupal project should be downloaded. See the links above for instructions on these topics.

To download contributed Drupal modules or themes with composer:

  • Run composer require drupal/<modulename> 
  • For example: composer require drupal/token
  • This needs to be executed at the root of your Drupal install

Composer will then automatically update your composer.json as follows:

{
    "require": { 
        "drupal/token": "1.x-dev"
    }
} 

Composer will download the module and all the possible dependencies it may have.

  • You can enable the module either by using the normal browser user interface 
  • If you use Drush, you can enable the module by using drush en <modulename> -y  and to check status use drush pm-list

You can use either the project name, or the specific module name within a project when requiring modules:

  • Composer will download the whole project that contains a particular module.
  • For example, if you need the fe_block module from the features_extra project you can do either from the following options:
    • composer require drupal/features_extra
    • composer require drupal/fe_block

Specifying a version

You can specify the version of the module / theme you want to download as follows:

composer require "drupal/<modulename>:<version>" 

For example:

composer require "drupal/simple_fb_connect:~3.0"
composer require "drupal/ctools:3.0.0-alpha26"
composer require "drupal/token:1.x-dev"

To avoid problems on different terminals/shells, surround the version using double quotes as in the examples above. In these examples, the versions map as follows:

  • ~3.0: maps to the latest stable 8.x-3.x release of the module.
  • 3.0.0-alpha26: maps to version 8.x-3.0-alpha26
  • 1.x-dev: maps to 8.x-1.x-dev 

It is recommended to indicate the version of the contributed module that you want to download. In the example above, Simple FB Connect can be updated to a later version of the 8.x-3.x branch but Composer will not automatically update to 8.x-4.x if it would be released.

About semantic versioning

Drupal.org contributed projects are currently not versioned with true semantic versioning. However, the Composer service on Drupal.org translates the Contrib project version schema into a semver format that Composer can understand. This 'semver shim' will also allow Drupal.org to be flexible if the versioning standard for Contrib changes. The key element to this shim is that each major version of Drupal Core has a separate endpoint, to prevent collisions between the D7 version of a module and the D8 version

Example D7 Endpoint Version Mapping
Current Format Translated Format
{Platform.x}-{major}.{minor}-{stability#} {major}.{minor}.0-{stability}{#}
7.x-3.4-beta2 3.4.0-beta2
7.x-2.10-rc2 2.10.0-rc2
7.x-1.0-unstable3 unstable releases will not be translated, and not available to composer
7.x-1.0-alpha5 1.0.0-alpha5
7.x-0.1-rc2 0.1.0-rc2
7.x-1.x-dev 1.x-dev

Using Composer search

Drupal.org's composer endpoints for Drupal 7 and Drupal 8 both support the Composer search function - so you can also search for Drupal projects from the command line. The format for using Composer search is:

composer search views 

Using Composer browse

Drupal.org's composer endpoints for Drupal 7 and Drupal 8 both support the Composer browse function - so you can find additional information about Drupal projects from the command line. The format for using Composer browse is:

composer browse drupal/token 

Define Drupal.org as Composer repository if needed

You can skip this section if you downloaded Drupal 8 core using 'drupal-composer/drupal-project' (Option A above) or 'hussainweb/drupal-composer-init' (Option C above) or if you're using Drupal 8.3.0 or later.

Composer uses Packagist.org as the default repository to discover packages. Drupal contributed modules and themes are not listed on Packagist. Instead, Drupal.org provides its own directory for Composer to use. Therefore you will need to add Drupal.org as a Composer Repository to your Drupal site's composer.json file.

  • You can either modify your composer.json manually or you can use the commands listed below.
  • Do not confuse your Drupal site's composer.json (located in your repository root) with Drupal core's composer.json (located in the core directory) or the composer.json belonging to a contributed project.

Drupal.org provides two separate composer repository endpoints: one for Drupal 7 and one for Drupal 8.

  • To use Composer with Drupal 7, use the repository url:https://packages.drupal.org/7
  • To use Composer with Drupal 8, use the repository url:https://packages.drupal.org/8

To add the repository from the command line you should execute the following command from your repository root:

  • Run composer config repositories.drupal composer https://packages.drupal.org/7 

Composer will then automatically update your Drupal site's composer.json file with a repositories object of the format:

{ 
    "repositories": { 
        "drupal": {
            "type": "composer",
            "url": "https://packages.drupal.org/7" 
        }
    }
} 

This will configure composer to look up Drupal modules, themes, etc. from Drupal.org. Once you have added the appropriate Drupal.org composer endpoint for the version of Drupal you wish to use, you can use Composer as you would use it for any other PHP project.

Define the directories to which Drupal projects should be downloaded

You can skip this section if you downloaded Drupal 8 core using 'drupal-composer/drupal-project' (Option A above) or 'hussainweb/drupal-composer-init' (Option C above).

By default, Composer will download all packages to the 'vendor' directory. Clearly, this doesn't jibe with Drupal modules, themes, profiles, and libraries. To ensure that packages are downloaded to the correct path, Drupal uses the composer/installers package and ships with configuration for the directories for your Drupal site. The 'drupal/drupal' template does not ship with drupal-libary configuration so you need to add it to your composer.json:

"extra": {
    "installer-paths": {
        "core": ["type:drupal-core"],
        "libraries/{$name}": ["type:drupal-library"],
        "modules/contrib/{$name}": ["type:drupal-module"],
        "profiles/contrib/{$name}": ["type:drupal-profile"],
        "themes/contrib/{$name}": ["type:drupal-theme"],
        "drush/{$name}": ["type:drupal-drush"],
        "modules/custom/{$name}": ["type:drupal-custom-module"],
        "themes/custom/{$name}": ["type:drupal-custom-theme"]
    }
}

Note

Custom modules and themes paths requires composer/installers package v1.0.24 and up.

Define the directories for arbitrary packages that do not have a "drupal-*" type

If you would like to place an arbitrary Composer package in a custom directory, you may use the Composer Installers Extender.

For instance, if you'd like to place the Dropzone package (which does not have a type of drupal-library) in the same directory as other Drupal libraries, you would first composer require oomphinc/composer-installers-extender, then add the following configuration to your composer.json file:

"extra": {
    "installer-types": ["library"],
    "installer-paths": {
        "libraries/{$name}": [
            "type:drupal-library",
            "enyo/dropzone"
        ],
    }
}

Finally, you would composer require enyo/dropzone.

Managing existing sites using Composer

This chapter applies to Drupal 8 sites that were originally installed without using Composer.  

Download contributed modules and themes using Composer 

If you initially created your Drupal website without Composer (for example by manually downloading and extracting a tarball / zip file), you will need to modify your composer.json by adding drupal.org as Composer repository and by defining the directory where modules should be downloaded.

You can use the Composerize Drupal plugin for Composer to automatically generate an updated composer.json for you. It will add contributed modules, themes, and profiles that it discovers in your existing site.

The Composerize module can "generate a composer.json from your installed Drupal code base, which can be used to regenerate that code base by running composer install."

Alternatively, you can manually modify your composer.json file. Please refer to these sections on this page:

Note: You should modify the composer.json file that is at the root of your repository, not core/composer.json.

Updating Drupal 8 sites using Composer

As discussed above in this article, it is increasingly common that contributed modules require third party libraries. Due to the way Composer works, these libraries can't just be manually uploaded to the site's vendor folder.  Instead, Composer must be used to download the contributed module so that Composer can automatically also download the required dependencies.

However, once Composer is used to manage a single module, it also means that Composer needs to be used to manage and update Drupal core. The reason for this is that manual Drupal core updates replace the 'vendor' directory, removing the downloaded libraries required by the contributed module. 

For updating a Drupal 8 core, contributed modules and themes using Composer, please refer to Update procedure in Drupal 8

Patching projects using Composer

You can automatically apply patches to composer-built dependencies using cweagans/composer-patches. See the project's README.md file for specific instructions.

Note that patching a project's .info.yml file(s) is a little more complex. Find details and a workaround in this issue.