Drupal Composer recipes

In this post we want to share some recipes for using Composer, which we have accumulated while working with Drupal projects created using the Drupal Composer template. We will also look at how to transfer an existing Drupal project to Composer.

If you are still not using Composer in Drupal projects, you should start doing it right now! Drupal Composer template will help with cope with this task. Creating a new project is easy.

If you are still not sure, take a look at the benefits of Drupal Composer development:

• There is no need to store the code of the contact modules (and the kernel itself!) In your version control system.
• A single package management tool for everything: Drupal core, contrib modules, JS libraries, your own modules used in different projects, etc.
• The most simple and convenient patching of the kernel and modules.
• It is much easier to use Git submodules .

(All recipes imply the use of Drupal 8, but they should also work for Drupal 7)
')

Installing Contrib Modules

• composer require drupal/<MODULE_NAME>:~8.0 to install the latest stable release (or the latest dev version if there are no releases for Drupal 8 yet)
• composer require drupal/<MODULE_NAME>:dev-<BRANCH_NAME> to install the latest dev version
• composer require drupal/<MODULE_NAME>:dev-<BRANCH_NAME>#<COMMIT_HASH> to install a specific version

Upgrading Drupal Core and Modules

• composer update to update everything
• composer update --dry-run to check for updates
• composer update drupal/<MODULE_NAME> to update a specific module

Package patching

The cweagans / composer-patches plugin (included in the Drupal Composer template) uses the patches described in the “extra” section of the composer.json file:

  "extra": { "patches": { "<PACKAGE/NAME>": { "<PATCH DESCRIPTION>": "<PATH/TO/PATCH/OR/URL>", ... }, ... } } 

Example:

  "extra": { "patches": { "drupal/core": { "Fix language detection": "patches/2189267-24.patch" } } } 

After the patch is added, run:

• composer install to apply patch
• composer update nothing (or composer update --lock ) so that the composer-patches plugin composer update --lock necessary changes in the composer.lock file

Installing custom / forked modules with Github

If the module repository contains its own composer.json file

Register the repository in the “repositories” section of the composer.json file:

  "repositories": [ { "type": "vcs", "url": "https://github.com/<REPOSITORY/NAME>" }, ... ], 

Use composer require drupal/<MODULE_NAME>:dev-<BRANCH_NAME>#<COMMIT_HASH> to install the module.

If the composer.json file is not in the module repository

Use a slightly more advanced version:

  "repositories": [ { "type": "package", "package": { "name": "drupal/<MODULE_NAME>", "version": "dev-custom", "type": "drupal-module", "source": { "type": "git", "url": "git@github.com:<REPOSITORY/NAME>.git", "reference": "<BRANCH-NAME>" } } }, ... ], 

Use composer require drupal/<MODULE_NAME>:dev-custom#<COMMIT_HASH> to install the module.

If the target directory should differ from modules / contrib

In addition to the above recipes, use the composer / installers plugin:

  "extra": { "installer-paths": { "web/modules/custom/<MODULE_NAME>": ["drupal/<MODULE_NAME>"], ... } } 

Installing JS Library

Popular JS libraries can be easily installed using Composer, since they (most likely) already exist in the Packagist repository. The difficulty lies in the fact that most Drupal modules require the installation of JS libraries in the “libraries” directory, while Composer installs them in the “vendor” directory.

The composer / installers plugin can reassign the installation path, but only for those packages that specify it as a dependency. Thus, you need to replace the library's composer.json file by specifying a dependency on the composer / installers in it.

Take a look at an example:

  "repositories": [ { "type": "package", "package": { "name": "enyo/dropzone", "version": "4.3", "type": "drupal-library", "source": { "url": "https://github.com/enyo/dropzone.git", "type": "git", "reference": "master" }, "dist": { "url": "https://github.com/enyo/dropzone/archive/v4.3.0.zip", "type": "zip" }, "require": { "composer/installers": "~1.0" } } }, ... ], ... "extra": { "installer-paths": { "web/libraries/{$name}" : ["type:drupal-library"], ... } } 

After this code is added to composer.json, run composer require enyo/dropzone:4.3 to install the library. Notice that we specified a specific version and added a “dist” section so that Composer could download the zip archive instead of cloning the repository.

We switch the existing package to the forked version

Register the fork repository in composer.json:

  "repositories": [ { "type": "vcs", "url": "https://github.com/<REPOSITORY/NAME>" }, ... ], 

Run composer require <PACKAGE/NAME>:dev-<BRANCH_NAME>#<COMMIT_HASH>

Switch existing Drupal 8 project to Composer

• Make backup;)
• Delete everything that Composer will manage: the Drupal "core" directory, contrib modules, etc.
• Delete all root Drupal files, such as index.php, update.php, README.txt ... All of them.
• Create a “web” directory in the project root and move all remaining Drupal directories there (sites, modules, themes, libraries, profiles, etc.)
• Copy the Drupal Composer template files to the root of the project.
• Prepare a list of versions of the contrib modules used in the project, the Drupal core and everything else that Composer will manage. Then run composer require specific version for each dependency. You will need to translate the Drupal version into the Composer version, here are some examples:
  
  
  • drupal/core:8.1.8 it all fits
  • drupal/admin_toolbar:8.1.15 implies admin_toolbar 8.x-1.15
  • drupal/ctools:8.3.0-alpha26 implies ctools 8.x-3.0-alpha26
  • drupal/config_installer:dev-8.x-1.x#a16cc9acf84dd12b9714def53be0ce280a5b0c1a implies the dev version of the config_installer created from the a16cc9a branch 8.x-1.x
• In the “require” section of the composer.json file, change the versions of the Drupal core and the contact modules to “~ 8.0”. This will make future updates possible.
• Run composer drupal-scaffold , this will create the necessary root Drupal files.
• Make sure your web server uses the “web” directory as web root.