Dependency Management

Composer usage overview

Composer should be used to manage Drupal core, all contributed dependencies, and most third party libraries. The primary exception to this is front end libraries that may be managed via a front-end specific dependency manager, such as Bower or NPM.

Why do we use Composer for dependency management? It is the dependency manager used by Drupal core.

Make sure to familiarize yourself with basic usage of Composer, especially on how the lock file is used. In short: you should commit both composer.json and composer.lock to your project, and every time you update composer.json, you must also run composer update to update composer.lock. You should never manually edit composer.lock.

You should understand:

  • Globally install pretissimo for parallelized composer downloads:

    composer global require "hirak/prestissimo:^0.3"
    
  • If you have xDebug enabled for your PHP CLI binary, it is highly recommended that you disable it to dramatically improve performance.

Contributed projects and third party libraries

All contributed projects hosted on drupal.org, including Drupal core, profiles, modules, and themes, can be found on Drupal packagist. Most non-Drupal libraries can be found on Packagist. For any required packaged not hosted on one of those two sites, you can define your own array of custom repositories for Composer to search.

Note that Composer versioning is not identical to drupal.org versioning.

Resources

Add dependencies

To add a new package to your project, use the composer require command. This will add the new dependency to your composer.json and composer.lock files, and download the package locally. E.g., to download the pathauto module run,

    composer require drupal/pathauto

Commit composer.json and composer.lock afterwards.

Update dependencies (core, profile, module, theme, libraries)

To update a single package, run composer update [vendor/package]. E.g.,

    composer update drupal/pathauto

To update all packages, run composer update.

Commit composer.json and composer.lock afterwards.

Remove dependencies

To remove a package from your project, use the composer remove command:

    composer remove drupal/pathauto

Commit composer.json and composer.lock afterwards.

Patch a project

Please see patches/README.md for information on patch naming, patch application, and patch contribution guidance.

Modifying BLT's default Composer values

BLT merges default values for composer.json using wikimedia/composer-merge-plugin:

    "merge-plugin": {
        "require": [
            "vendor/acquia/blt/composer.required.json",
            "vendor/acquia/blt/composer.suggested.json"
        ],
        "include": [
            "blt/composer.overrides.json"
        ],
        "merge-extra": true,
        "merge-extra-deep": true,
        "merge-scripts": true,
        "replace": true
    },

This merges the require, require-dev, autoload, autoload-dev, scripts, and extra keys from BLT's own vendored files. The merged values are split into three groups

  1. composer.require.json: These packages are required for BLT to function properly. You may change their versions via comopser.overrides.json, but you should not remove them.
  2. composer.suggested.json: You may remove the suggested packages by deleting the vendor/acquia/blt/composer.suggested.json line from your composer.json.
  3. composer.overrides.json: You may customize this file in order to override the version constraints that BLT defines in composer.required.json.

Merging in additional composer.json files

In situations where you have local projects, e.g. a custom module, that have their own composer.json files, you can merge them in by including the composer-merge-plugin. Reference these additional composer.json files in the extra section of your root composer.json file.

    "extra": {
      "merge-plugin": {
        "require": [
          "docroot/modules/custom/example/composer.json"
        ]
      }
    }

Front end dependencies

Drupal 8 does not have a definitive solution for downloading front end dependencies. The following solutions are suggested:

  • Load the library as an external library. See Adding stylesheets (CSS) and JavaScript (JS) to a Drupal 8 module.
  • Use a front end package manager (e.g., NPM) to download your dependencies. Then use BLT's frontend-build and post-deploy-build target-hooks to trigger building those dependencies. E.g., call npm install in your theme directory via these hooks.
  • Add the library to composer.json via a custom repository. Designate the package as a drupal-library and define a installer-paths path for that package type to ensure that it is installed to docroot/libraries. Ensure that it can be discovered in that location. See example composer.json.

Contributed projects should provide the ability to download and discover the libraries. If you are using a contributed project, it is suggested that you patch the project to support one of these strategies.

If you cannot, then commit the dependency. You can use a custom .gitignore file for you project, ensure that it is copied to the deployment artifact, and supply your own, custom .gitignore file to be used in the deployment artifact.