Information for: DEVELOPERS   PARTNERS

Using Composer with Drupal 8 sites

Composer is a tool for managing PHP dependencies for your website or application. Composer gives you the flexibility to declare the libraries your project depends on, and it will install and update them for you.

For full instructions about downloading and installing Composer for your operating system, see the Composer’s Getting Started guide.

Using Composer with Acquia Cloud

Due to Composer not being installed on Acquia Cloud, Acquia recommends you install Composer locally and use it with your local copy to perform updates and manage dependencies. You can then deploy your build artifact to your Acquia Cloud environments using the Acquia Cloud pipelines feature.

To follow best practices with Composer, you must maintain a source code (source) repository for your project separate from your Acquia Cloud (build) repository. Your source repository must contain the least amount of code required to build your project, such as a composer.json file, composer.lock file, and any custom modules or settings. The source repository must not contain copies of your Composer dependencies. Your build repository (hosted on Acquia Cloud) must contain static snapshots, called build artifacts, of your entire codebase (including Composer dependencies) ready for deployment to Acquia Cloud.

To move code between your source and build repositories, you can use one of the following methods:

  • Copy the necessary files locally
  • Use a continuous integration service, such as the Acquia Cloud pipelines feature
  • Use a tool automating the process, such as Acquia BLT

You can use a Composer-based workflow with a single repository (not recommended). Using a single repository creates a brittle development workflow, which can make it difficult to maintain code consistency. For instance, with a single repository, you must keep the versions of dependencies in composer.json and the versions of dependencies you commit to the repository in sync, which introduces a high risk of human error.

If you cannot use the Acquia Cloud pipelines feature, you can use Composer based on the following methods:

  • Using Acquia BLT deploy commands, as described in the Acquia BLT Deployment workflow.
  • Installing Composer through Live Development (not recommended)
    You can install Composer in Acquia Cloud by enabling Live Development and following the normal Git workflow for checking out code (including adding changed flags, committing changes, and pushing to origin). After you install Composer, you must enable Live Development mode to begin using Composer on Acquia Cloud. By default the .gitignore file ignores the Vendor directory, which makes sense if you use Composer on Acquia Cloud directly.

Encrypting Composer variables

To encrypt Composer variables in Acquia Cloud pipelines, see Encrypting keys and variables.

When encrypting the COMPOSER_AUTH variable using the Encrypt Credentials field in the Acquia Cloud interface, ensure you use single quotes at the beginning and end of the json, and use double quotes inside the curly brackets, as in the following example:

'{"http-basic": {"mysite.com": {"username": "myuser", "password": "mypassword"}}}'

Failing to follow the preceding code format can generate the following UnexpectedValueException error:

COMPOSER_AUTH environment variable is malformed, should be a valid JSON object

Using Composer with Drupal

In Drupal versions 8.1 and greater, Drupal core uses Composer to manage dependencies, which can include Drupal modules. For more information, see the following Drupal.org resources:

Starting with Drupal 8.4, a minimum version of Drush 8.1.12 is required if installed globally, and Drush 8.1.15 if required at the project level using Composer.

Migrating into a Composer-managed build

If you migrate an existing Drupal 8 website into a Composer-managed build, you must build a composer.json file including all the packages your existing website requires. For more information about the migration process, see the Composer: Migrate an existing D8 site into a Composer-managed build documentation page.

Patching with Composer

To enable patching through Composer, complete the following steps:

  1. Install the composer-patches project with Composer:

    composer require cweagans/composer-patches
    
  2. Add the following to the extra section of the composer.json file located above the docroot:

    "enable-patching": true,
       "patches": {
          "drupal/[module_name]": {
            "Note regarding the nature of the patch being applied":
            "https://www.drupal.org/files/issues/[patch_name].patch"
          }
       }
    

Update the [module_name] and [patch_name] according to your patch file from Drupal.org, or you can add your patches in the patches directory directly above your docroot directory, and then record the full path in your patches.make file.