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.
Due to Composer not being installed on Cloud Platform, 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 Cloud Platform environments using the Cloud Platform pipelines feature.
To follow best practices with Composer, you must maintain a source code
(source) repository for your project separate from your Cloud Platform
(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 Cloud Platform) must contain static snapshots,
called build artifacts, of your entire codebase (including Composer
dependencies) ready for deployment to Cloud Platform.
To move code between your source and build repositories, you can use one of the following methods:
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 Cloud Platform pipelines feature, you can use Composer based on the following methods:
deploy
commands, as described in the Acquia BLT
Deployment workflow..gitignore
file ignores the
Vendor
directory, which makes sense if you use Composer on
Cloud Platform directly.To encrypt Composer variables in Cloud Platform pipelines, see Encrypting keys and variables.
When encrypting the COMPOSER_AUTH
variable using the Encrypt
Credentials field in the Cloud Platform 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
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.
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.
To enable patching through Composer, complete the following steps:
Install the composer-patches
project with Composer:
composer require cweagans/composer-patches
Add the following to the extra section of the composer.json
file
located above the docroot directory:
"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.
Alternately, patches can be taken out of the root composer.json
and
included in a separate file. This is a cleaner way of tracking them when you
are dealing with various patches.
The following code block would be added to your composer.json
:
{
// [...]
"extra": {
// [...]
"patches-file": "composer.patches.json"
}
}
Patches are added to a composer.patches.json
text file as follows:
{
"patches": {
"vendor/project": {
"Message describing the patch": "https://www.drupal.org/url/to/patch/file.patch"
}
}
}