Gnu/Linux: composer

by Gisle Hannemyr

This chapter provides some notes on using composer on a Drupal 7 website.

Introduction
Installing composer
Useful commands
Final word

Drupal project discussed in this chapter: Composer Manager.

Introduction

Composer is a dependency manager for PHP designed and developed by Nils Aderman and Jordi Boggiano and first released in 2012. It is used by the Drupal.org community to manage projects, including managing a Drupal website.

This documnetation will use this terminology:

siteroot: The directory above the webroot. This is the canonical place for the project's composer.json file and the vendor directory.
webroot: The directory pointed to by Apache's DocumentRoot. This is where the site's root index.php or index.html lives.

See the Drupal 8 version of this page for:

Installing composer

This is covered in other chapters:

RHEL7
Ubuntu

Setting up Composer Manager

Source: Composer Manager for Drupal 6 and Drupal 7.

Before starting to work with Composer on a Drupal 7 website, make sure that Composer Manager is enabled for the site.

note Unless you add keys to settings.php as described below, installing Composer Manager will install the composer file directory in the default location (i.e. /sites/default/files/composer). This is probably not where you want it. Delete it after completing the installation.

After you've installed Composer Manager on a Drupal 7 site, this appears on the error on the status page:

Composer Manager - Dependencies not installed
Composer's install command must be run to generate the autoloader and install the required packages.
Refer to the instructions on the Composer Manager project page for installing packages.

If you have full access to the file system, the best practice is to maintain a project structure where the composer files and vendor directory exist alongside the document root. This can be achieved by first changing premissions so that the both the webmaster and the web server has permission to write the document root.

Then add the following keys to settings.php and make sure the siteroot directory is writeable by the web server.

$conf['composer_manager_vendor_dir'] = '../vendor';
$conf['composer_manager_file_dir'] = '../';

Or you may navigate to Configuration » System » Composer Manager » Settings and change the default settings to the following:

Vendor Directory: ../vendor
Composer File Directory: ../

Leave both boxes below checked and press “Save configuration”. This may produce the follwing error:

The composer.json file was not found.
Run drush composer-json-rebuild on the command line or submit the Rebuild composer.json file button on this page to build the file.

This drush command does not exist, but the second option works.

Now position yourself in the siteroot (the directory that contains composer.json as use the CLI to run the following command:

$ composer install

This produces composer.lock and the vendor directory, making Composer ready to use.

note The recommended settings are not the defaults because the siteroot may not be writable on the server. The "Composer File Directory" must writable by the web server so the automatic building of composer.json works out of the box.

Check permissions. Both the webmaster and the web-server group shall have write permission to composer.json and composer.lock.

Enabling and disabling modules

Under Drupal 7, Drush is still the recommended tool for disabling and enabling modules that has dependencies declared in a composer.json, as it will automatically update Composer dependencies when you do so.

Multisite

It is recommended that each multisite installation has its own library space since the dependencies are tied to which modules are enabled or disabled and can differ between sites. Add the following snippet to settings.php to group the libraries by site in a directory outside of the document root:

# Capture the site dir, e.g. "default", "example.localhost", etc.
$site_dir = basename(__DIR__);
$conf['composer_manager_vendor_dir'] = '../lib/' . $site_dir . '/vendor';
$conf['composer_manager_file_dir'] = '../lib/' . $site_dir;

Note that you need to be positioned in the directory containing the root composer.json to execute any command that interacts with the root composer.json.

note The sites/*/ directories may seem like an obvious location for the libraries, however Drupal removes write permissions to these directories on every page load which can cause frustration.

Production environments

Dependencies should be managed in development environments and not in production. Therefore it is recommended to disable the checkboxes that automatically build the composer.json file and run Composer commands when enabling or disabling modules on production environments.

Assuming that you can detect whether the site is in production mode via an environment variable, adding the following snippet to settings.php will disable the options where appropriate:

# Modify the logic according to your environment.
if (getenv('APP_ENV') == 'prod') {
  $conf['composer_manager_autobuild_file'] = 0;
  $conf['composer_manager_autobuild_packages'] = 0;
}

Final word

[mumble]

Last update: 2019-09-22 [gh].