Composer Manager for Drupal 8

Notice: As of Drupal 8.1, Drupal core directly uses Composer to manage dependencies, which can include Drupal modules. Rather than use Composer Manager, the new recommended workflow for a module with Composer dependencies will be to require the module itself through Composer. For more information, see: Using Composer in a Drupal project, Using Composer to install Drupal packages through Drupal.org.

Overview

Composer requires a Drupal site to have a single composer.json file and vendor/ directory.
Drupal 8 ships with a root composer.json file which should be edited to include any module requirements. The composer-merge-plugin is used to merge the requirements from core/composer.json into the root composer.json.

Composer Manager provides the following functionality:

• Discovers each module's composer.json file and adds it to the root composer.json merge list.
• Adds the Drupal Packagist to the list of repositories, allowing drupal modules to be required the same way as other packages
• The /admin/reports/composer-manager status report.

Provided commands

• composer drupal-rebuild: Rebuilds the root composer.json file (replace, repository, extra/merge-plugin/include keys).
• composer drupal-update: A shortcut for composer drupal-rebuild && composer update

Installation

1. Install the Composer Manager module
2. Run the module's init.php script on the command line in your Drupal root directory.
   (php PATH_TO_COMPOSER_MANAGER_MODULE/scripts/init.php).
   This registers the module's Composer command for Drupal core.
   Example:

   username@locahost:/var/www/SITENAME$ php modules/composer_manager/scripts/init.php
   

   You should see Composer Manager has been successfully initialized. once initialized properly.

3. Run composer drupal-update from the the root of your Drupal directory.
   Example:

   username@locahost:/var/www/SITENAME$ composer drupal-update
   

Workflow

1. Download the desired modules (such as Commerce).
2. Run composer drupal-update from the root of your Drupal directory.
   This rebuilds composer.json and downloads the new module's requirements.
   Example:

   username@locahost:/var/www/SITENAME$composer drupal-update
   

3. Install the modules.

People who can't run composer drupal-update on their servers can do the process locally, then commit the results.

You can also rebuild the composer.json file by simply running composer drupal-rebuild.

If you want to update the dependencies for a single module (after rebuilding composer.json), you can run composer update drupal/example_module.

Updating Drupal Core

1. Follow the instructions over at Update procedure in Drupal 8, but do not Run update.php (stop before step 6).
2. Run composer drupal-update.
3. Continue with the standard update procedure: Run drush updatedb or run update.php (step 6).

Drush integration

When downloading or installing a module with Drush, composer drupal-update will automatically run afterwards.

Sometimes it is desirable to turn off this behavior, if you want to run composer drupal-update once after all downloads, or need to pass custom arguments to it.
In that case, set the SKIP_COMPOSER_UPDATE environment variable:

export SKIP_COMPOSER_UPDATE=1 && drush dl commerce

You can then rebuild composer.json manually, and call composer update with custom arguments:

composer drupal-rebuild && composer update --prefer-source

Build process workflow

Composer Manager can also run without a Drupal installation, making it usable as a part of a Drush Make site build process.

drush make test.make target
cd target
php modules/composer_manager/scripts/init.php
composer drupal-rebuild
composer update -n --lock --verbose

The site is now ready to be installed.

Adding dependencies to your module

Just include a composer.json file in your module root. The file should at least contain a name and requirements like so (requiring a Mailchimp library as an example):

{
  "name": "drupal/mymodule",
  "require": {
    "mailchimp/mailchimp": "2.0.6"
  }
}

To make sure that the user ran Composer and the library is present, add a hook_requirements implementation to your .install file. Example from Address module:

/**
 * Implements hook_requirements().
 */
function address_requirements($phase) {
  $requirements = [];
  if ($phase == 'install') {
    if (!class_exists('\CommerceGuys\Addressing\Repository\AddressFormatRepository')) {
      $requirements['addressing_library'] = [
        'description' => t('Address requires the commerceguys/addressing library.'),
        'severity' => REQUIREMENT_ERROR,
      ];
    }
  }

  return $requirements;
}

Note: Your module should not depend on Composer Manager. The module itself is not required to be enabled for commands to work, and other users might use different Composer strategies that don't involve Composer Manager.