Managing dependencies for a contributed project

The following guidelines are intended for maintainers of projects on drupal.org.

If you maintain a project (module, theme, profile, etc.), these instructions will help with how to add Drupal dependencies and non-Drupal dependencies to your projects' composer.json.

Requiring non-Drupal PHP packages with Composer

Any non-Drupal PHP dependencies should be declared in your composer.json file in the standard way, by adding a require statement specifying the package name from Packagist and the version.

{ "require": { "guzzle/guzzle": "3.9.3" } } 

Requiring Drupal Projects in your Project

First, if all your dependencies are Drupal projects, you do not need to create a composer.json file; Drupal.org can derive that information from the dependencies specified in your info.yml file to allow others to include your contributed project in their own projects.

Although this information will be merged with the dependency information from any composer.json, it is considered a best practice to also include your Drupal dependencies in case you need an explicit composer.json for non-Drupal packages. To do this, you can simply add require statements to your composer.json to specify dependencies on Drupal modules or themes. Do note that Drupal.org translates the Drupal versioning scheme into a semantic versioning format for Composer, by adding a .0 for the patch version.

{ "require": { "drupal/token": "^1.5" } } 

Managing versions

Composer allows you to specify what version of a package you would like to use with several degrees of specificity. By using version operators you can specify an exact version, a range of versions, or stability constraints. You can find detailed examples on getcomposer.org, but here are a few examples to illustrate the principle with Drupal projects:

This example specifies an exact version:

{ "require": { "drupal/token": "1.0.0-alpha2" } } 

However, you can also specify a range of versions. This example specifies any release greater than 1.0.0 but less than the next major release.

{ "require": { "drupal/token": ">=1.0.0 <2.0.0" } } 

There are also a few shorthand operators for specifying version ranges. The tilde character is short for 'greater than or equal to this version, but less than the next major release.'

{ "require": { "drupal/token": "~1.1" } } 

The caret operator functions much like the tilde operator but is more strict about the semver format. This example is equivalent to: ">=1.0.0 <2.0.0"

{ "require": { "drupal/token": "^1.0.0" } } 

Specifying minimum versions of a module is a perfectly acceptable practice, especially if your project depends on a feature or API only added in that version, but specifying a maximum minor or patch version should generally be avoided - as it could prevent end-users from receiving important updates like security releases.

Dependencies for tests

For some contributed modules, certain automated tests require additional contributed modules to be installed, which are not dependencies of the project as a whole. In this case, you will find that you can run the test successfully on your local machine (since you can install the necessary module there before you run the test), but when you try to have the automated test runner ("DrupalCI") run the test from drupal.org, it fails. To fix this problem, there are two options:

1. Add the module to the test_dependencies section of the module.info.yml file. For this to work, the change to the info.yml file must be committed to the git repository before the test run starts, in order for the test runner to discover the dependency.
2. Add the dependency to the composer.json file as described above, but replace "require" with "require-dev".