Skip to content

Latest commit

 

History

History
92 lines (55 loc) · 5.77 KB

dependency-management.md

File metadata and controls

92 lines (55 loc) · 5.77 KB
Raw

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:

Recommended tools and configuration

  • 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, a drupal.org hosted packagist server. You must specify this special URL in your composer.json so that Composer is able to discover such 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 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 --with-dependencies

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.md for information on patch naming, patch application, patch ignoring, and patch contribution guidance.

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 source:build:frontend-assets target-hook to trigger building those dependencies, e.g., call npm install in your theme directory via these hooks. See Frontend management for more information.
  • Commit the library to the repository, typically in docroot/librares.
  • Add the library to composer.json via 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, 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.