Composer usage overview¶

Composer should be used to manage Drupal core, all contributed dependencies, and most third party libraries in Drupal 8 and above. The primary exception to this is front-end libraries, which can be managed using 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.

Be sure to familiarize yourself with Composer's basic usage, especially how the lock file is used. You should commit both the composer.json and composer.lock files to your project, and every time you update the composer.json file , you must also run the following command to update the composer.lock file:

composer update

Never manually edit the composer.lock file.

Notable Composer concepts¶

• Why dependencies should not be committed
• The role of composer.lock
• How to use version constraints
  • Why using unbound version constraints is a bad idea
• The difference between require and require-dev

Recommended tools and configuration¶

• Globally install pretissimo for parallelized composer downloads by running the following command:

  copy

  composer global require "hirak/prestissimo:^0.3"

• If you have Xdebug enabled for your PHP CLI binary, to dramatically improve performance it is highly recommended that you disable Xdebug.

Contributed projects and third-party libraries¶

You can find all contributed projects hosted on Drupal.org (including Drupal core, profiles, modules, and themes) on Drupal Packagist, a Drupal.org-hosted packagist server. You must specify this URL in your composer.json file by adding the following code to allow Composer to discover the packages:

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

Most non-Drupal libraries can be found on Packagist.

For any required packaged not hosted by the preceding websites, you can define your own array of custom repositories for Composer to search.

Note: Composer versioning is not identical to Drupal.org versioning.

Composer resources¶

• Composer Versions
• Using Composer to Manage Drupal Site Dependencies
• Drupal Composer package naming conventions
• Packagist: Find non-drupal libraries and their current versions.

Installing dependencies¶

To install a new package to your project, use the composer require command. This command adds the new dependency to your composer.json and composer.lock files, and downloads the package locally. For example, to download a module, run the following command, replacing [module] with the module you want to download:

composer require drupal/[module]

After you run the command, be sure to commit your composer.json and composer.lock files.

Updating dependencies (core, profile, module, theme, libraries)¶

To update a single package, run the composer update [vendor/package] command, replacing [module] with the module you want to update:

composer update drupal/[module] --with-dependencies

To update all packages, run the following command:

composer update

After you run the command, be sure to commit your composer.json and composer.lock files.

Removing dependencies¶

To remove a package from your project, use the composer remove command, replacing [module] with the module you want to remove:

composer remove drupal/[module]

After you run the command, be sure to commit your composer.json and composer.lock files.

Patching a project¶

For information about patch naming, patch application, patch ignoring, and patch contribution guidance, see patches.

Front-end dependencies¶

Drupal doesn't have a definitive solution for downloading front-end dependencies. Acquia suggests you refer to the following solutions:

• 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 (such as NPM) to download your dependencies. Then, use Acquia BLT's source:build:frontend-assets target-hook to trigger building those dependencies (such as call npm install) in your theme directory using these hooks. For more information, see Front-end development and Acquia BLT.
• Commit the library to the repository, typically in docroot/librares.
• Add the library to your composer.json file by using a custom repository. Designate the package as a drupal-library and define an 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, commit the dependency. You can use a custom .gitignore file for your project.

Ensure the dependency is copied to the deployment artifact, and supply your own, custom .gitignore file to use in the deployment artifact.