Composer Manager

Composer Manager provides a gateway to the larger PHP community by enabling Backdrop modules to more easily use best-in-breed libraries that are managed by Composer.

There are many challenges when using Composer with Backdrop, so the primary goal of this module is to work around them by wrapping Composer with common Backdrop workflows so that module developers and site builders can use the thousands of standards-compliant, platform agnostic PHP libraries with as little friction as possible.

Installation

• Install this module using the official Backdrop CMS instructions
• Refer to the Maintaining Dependencies section for installing and updating third-party libraries required by contributed modules
• Refer to the Best Practices section for recommended module configurations according to your environment

Usage For Site Builders

Maintaining Dependencies

As modules are enabled and disabled, Composer Manager gathers their requirements and generates a consolidated composer.json file in the "Composer File Directory" as configured in Composer Manager's settings page. There are two ways to install and update the contributed modules' dependencies:

Automatically With Drush (Recommended)

Using drush en and drush dis to enable and disable modules respectively will automatically generate the consolidated composer.json file and run the appropriate Composer commands to install and update the required dependencies.

This technique introduces the least amount of friction with existing workflows and is strongly recommended.

The following Drush commands are also available:

• drush composer-json-rebuild: Force a rebuild of the consolidated composer.json file
• drush composer-manager [COMMAND] [OPTIONS]: Pass through commands to Composer, refer to the cli tool's documentation for available commands and options.

Manually With Composer

If you do not wish to use Drush, you must manually use Composer's command line tool to install and update dependencies whenever modules are enabled or disabled. The following steps illustrate the workflow to maintain the dependencies required by contributed module:

• Visit admin/modules and enable / disable the modules that have dependencies
• Change into the the "Composer File Directory" as configured in Composer Manager's settings page which is where the consolidated composer.json file was generated
• If necessary, download and install the Composer tool
• Run php composer.phar install --no-dev on the command line, replace install with update when updating dependencies

Refer to Composer's documentaton for more details on how Composer works.

Configuring Composer Manager

Visit admin/config/system/composer-manager/settings as a user with the administer site configuration permission to configure Composer Manager.

Best Practices

Unfortunately there is arguably no 80% use case that guides sane defaults. Site builders will likely have to configure Composer Manager according to their environment, so this section outlines best practices and techniques to help guide a sustainable, reliable installation.

Recommended Settings

It is recommended to maintain a project structure where the composer files and vendor/ directory exist alongside the document root. This can be achieved by modifying the following options in Composer Manager's settings page.

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

You can also set the options in settings.php by adding the following variables:

$config['composer_manager.settings']['vendor_dir'] = '../vendor';
$config['composer_manager.settings']['file_dir'] = '../';

NOTE: The recommended settings are not the defaults because we cannot assume that this structure is viable for all use cases. Furthermore, the "Composer File Directory" is set to a path we know is writable by the web server so the automatic building of composer.json works out of the box.

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__);
$config['composer_manager.settings']['vendor_dir'] = '../lib/' . $site_dir . '/vendor';
$config['composer_manager.settings']['file_dir'] = '../lib/' . $site_dir;

NOTE: The sites/*/ directories may seem like an obvious location for the libraries, however Backdrop 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') {
  $config['composer_manager.settings']['autobuild_file'] = 0;
  $config['composer_manager.settings']['autobuild_packages'] = 0;
}

Usage For Module Maintainers

Module maintainers can use Composer Manager to maintain their dependencies by creating a composer.json file in the module's root directory and adding the appropriate requirements. Refer to Composer's documentation for details on adding requirements.

It is recommended to use version ranges and tilde operators wherever possible to mitigate dependency conflicts.

You can also implement hook_composer_json_alter(&$json) to modify the data used to build the consolidated composer.json file before it is written.

Maintaining A Soft Dependency On Composer Manager

@todo

Accessing The ClassLoader Object

Once the autoloader is registered, you can retrieve the ClassLoader object by calling \ComposerAutoloaderInitComposerManager::getLoader(). The following example uses this technique with Doctrine's Annotations library which requires access to the loader object.

use Doctrine\Common\Annotations\AnnotationRegistry;

$loader = \ComposerAutoloaderInitComposerManager::getLoader();
AnnotationRegistry::registerLoader(array($loader, 'loadClass'));

Relying on composer manager in .install

Composer manager will automatically handle the autoloader in hook_init(), so modules generally don't have to worry about triggering the autoloader. However there are occasions where hook_init() isn't invoked such as during install and update.php. If you rely on the autoloader in a .install file, you have to make sure the autoloader is triggered by running composer_manager_register_autoloader() at the beginning of your update function or your hook_install() implementation.

Why can't you just ... ?

The problems that Composer Manager solves tend to be more complex than they first appear. This section addresses some of the common questions that are asked as to why Composer Manager works the way it does.

Why can't you just run "composer install" in each module's root directory?

If a module contains a composer.json file, running composer install in its root directory will download all requirements and dependencies to vendor/ directories with their own autoloaders. Relying on this technique poses multiple challenges:

• Duplicate library code when modules have the same dependencies
• Unexpected classes being sourced depending on which autoloader is registered first
• Potential version conflicts that aren't detected since each installation is run in isolation

To highlight the challenges, let's say module_a requires "guzzle/http": "3.7.*" and module_b requires "guzzle/service": ">=3.7.0". At the time of this post, running composer install in each module's directory will result in version 3.7.4 of guzzle/http being installed in module_a's vendor/ directory and version 3.8.1 of guzzle/service being installed in module_b's vendor/ directory.

Because guzzle/service depends on guzzle/http, you now have duplicate installs of guzzle/http. Furthermore, each installation uses different versions of the guzzle/http component (3.7.4 for module_a and 3.8.1 for module_b). If module_a's autoloader is registered first then you have a situation where version 3.8.1 of \Guzzle\Service\Client extends version 3.7.4 of \Guzzle\Http\Client.

Composer Manager's Solution

Composer Manager finds all composer.json files in each enabled module's root directory and attempts to gracefully merge them into a consolidated composer.json file. This results in a single vendor directory shared across all modules which prevents code duplication and version mismatches. For the use case above, Composer will resolve both guzzle/http and guzzle/service to version 3.7.4 which is a more consistent, reliable environment.

Challenges With Composer Manager

The challenge of Composer Manager's technique is when multiple modules require different version of the same package, e.g. "guzzle/http": "3.7.*" and "guzzle/http": "3.8.*". Composer Manager will use the version defined in the composer.json file that is associated with the module with the heaviest weight. Composer Manager will also flag the potential version conflict in the UI so the site builder is aware of the inconsistency.

Why can't you just manually maintain a composer.json file?

Manually maintaining a composer.json file provides a single library space that all modules can share, however relying on this technique poses multiple challenges:

• Site builder responsible for updating file when modules are enabled or updated
• Dependencies are decoupled from the module's codebase
• Multiple files must be maintained for each multisite installation

Composer Manager's Solution

Composer Manager automatically generates the composer.json file when modules are enabled and disabled, and there is an option in the UI with a corresponding Drush command that can rebuild the consolidated composer.json file on demand. Furthermore, using a Drush based workflow will automatically run the appropriate composer commands whenever modules are enabled or disabled, so the need to run Composer commands outside of normal workflows is reduced to module updates.

Challenges With Composer Manager

There are multiple challenges posed by Composer Manager's technique:

• Web server needs write access to the composer file directory
• Sane multisite configuration requires environment-specific settings.php configurations
• Must implement hook_composer_json_alter() in a module to modify composer.json

Composer Manager's Solution

Refer to the Why can't you just manually maintain a composer.json file? section.

Challenges With Composer Manager

Refer to the Why can't you just manually maintain a composer.json file? section.

Current Maintainers

• Laryn Kragt Bakker.
• Collaboration and co-maintainers welcome!

Credits

• Ported to Backdrop CMS by Laryn Kragt Bakker.
• Support has been provided by Aten Design Group.
• Maintained for Drupal by Bojan Živanović, Chris Pliakas, Andrew Berry, Nathaniel Hoag, and Richard Burford.

License

This project is GPL v2 software. See the LICENSE.txt file in this directory for complete text.