Add composer.json file

When developing custom modules, there are several scenarios where the developer is required to add a composer.json file to the module. Some of these scenarios depend on whether the custom module is intended to be shared with the community as a project on drupal.org.

If a module developer wants to use a PHP library hosted on packagist.org, they must add a composer.json file to their project.

If the module is a contributed module on drupal.org, has dependencies on other modules, and the developer wants to test changes to those dependencies using DrupalCI during development, they must include a composer.json file that expresses those Drupal module dependencies (DrupalCI can only detect changes in dependencies from patches within composer.json, not from .info or .info.yml files).

If a module developer wants to use more expressive constraints provided by composer.json, such as caret or tilde operators, these are only possible within composer.json. (Although Drupal itself will not enforce these constraints, they will be applied during the build process if the end user uses Composer to build their site.)

If a module has no dependencies or depends only on other Drupal modules, then composer.json is not required. However, having a composer.json file also does not have any negative effect.

Regardless of whether a developer has a composer.json file, their module’s Drupal dependencies must still be expressed in their .info.yml files so that Drupal can ensure the correct modules are enabled.

Define Your Module as a PHP Package

The broader PHP community uses Composer for package management; this is also the case in Drupal. For example, the Drupal project depends on the package “drupal/core.” The type of package “drupal/core” is defined as “drupal-core,” so Composer knows how to handle it. The composer/installers library defines several Drupal types. These are:

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

Here is a complete example of how the mobile_detect project uses composer.json to depend on an 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-or-later",
  "minimum-stability": "dev",
  "require": {
    "mobiledetect/mobiledetectlib": "~2.8"
  }
}

For naming your package, you should follow the Drupal Composer naming conventions.

Defining Dependencies in composer.json

If desired, you can define external dependencies for your module in composer.json. Drupal core will not automatically detect or manage these dependencies. To use the dependencies defined in the module’s composer.json file, you must use one of the following maintenance strategies:

• Install Drupal core and the module using Composer.
• Manually modify the composer.json file in the root directory of your Drupal installation.

For more information about Composer as a dependency manager for Drupal, see the comparison between Composer and Drush Make as dependency managers.

Adding Dependencies on Other Drupal Modules

By default, Composer only searches for packages published on Packagist when resolving dependencies. Most Drupal modules are not published there because Drupal has its own repository. Because of this, you may encounter error messages such as:

The requested package drupal/module could not be found in any version, there may be a typo in the package name.

You can tell Composer to look for Drupal modules in the packages.drupal.org repository by running the following command:

$ composer config repositories.drupal composer https://packages.drupal.org/8

This command will add the following section to your composer.json file:

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

Drupal 9 Compatibility

Having a composer.json file is not required for compatibility with Drupal 9. Drupal 9 is compatible with just an info.yml file. If your project includes a composer.json file, specifying compatibility with drupal/core is not mandatory for Drupal 9 compatibility. However, if you do include a version requirement for drupal/core in your require section, it must be compatible with Drupal 9.