Add a composer.json file

Last updated on
22 February 2018

When developing custom modules there are several scenarios that require the developer to add a composer.json file to their module. Some of these scenarios depend upon whether the custom module is intended to be contributed back to the community as a project on drupal.org.

If a module developer wishes to use a php library that is hosted on packagist.org, they must add a composer.json file to their project.

If a module is a contributed module on drupal.org, has dependencies on other modules, and wishes to test changes to those dependencies using drupalci as part of development, they must have a composer.json that expresses those drupal module dependencies (drupalci can only detect changes to dependencies in patches within composer.json, not in .info/info.yml files)

If a module developer wishes to use the more expressive constraints provided by composer.json, such as the caret or tilde operators, those are only possible in composer.json. (Though drupal itself will not be bound by those constraints, they will only be respected at build time, if the end user is using composer to build their site)

If a module does not have any dependencies, or the dependencies are solely other drupal modules, then a composer.json is not required. However, having a composer.json does not have a negative impact either.

Regardless of whether or not a developer has a composer.json file, their drupal module dependencies must still be expressed in their .info.ymlfiles so that drupal can ensure that the correct modules are enabled.

Define your module as a PHP package

The wider PHP community uses Composer to manage packages; this is also done in Drupal. For example, the Drupal project has a dependency on the "drupal/core" package. The "drupal/core" package has a type defined as "drupal-core" so Composer knows what to do with it. The composer/installers library defines a number of Drupal types. These are

  • drupal-module
  • drupal-theme
  • drupal-library
  • drupal-profile
  • drupal-drush

Here is a full example of how the mobile_detect project uses composer.json to depend on the external project mobiledetect/mobiledetectlib:

{
    "name": "drupal/mobile_detect",
    "description": "Mobile_Detect is a lightweight PHP class for detecting mobile devices.",
    "type": "drupal-module",
    "homepage": "https://drupal.org/project/mobile_detect",
    "authors": [
        {
            "name": "Matthew Donadio (mpdonadio)",
            "homepage": "https://www.drupal.org/u/mpdonadio",
            "role": "Maintainer"
        },
        {
            "name": "Darryl Norris (darol100)",
            "email": "admin@darrylnorris.com",
            "homepage": "https://www.drupal.org/u/darol100",
            "role": "Co-maintainer"
        }
    ],
    "support": {
        "issues": "https://drupal.org/project/issues/mobile_detect",
        "irc": "irc://irc.freenode.org/drupal-contribute",
        "source": "https://cgit.drupalcode.org/mobile_detect"
    },
    "license": "GPL-2.0+",
    "minimum-stability": "dev",
    "require": {
        "mobiledetect/mobiledetectlib": "~2.8"
    }
}

For naming your package, you must follow Drupal's Composer package naming conventions.

Defining dependencies in composer.json

You may optionally define external dependencies for your module in composer.json. Drupal core will not automatically discover or manage these dependencies. To utilize dependencies defined in a project's composer.json file, you must use one of the following maintenance strategies:

For more information on composer as a dependency manager for Drupal, review a comparison of Composer and Drush Make as dependency managers.