TL;DR: Use Composer instead of Drush Make for Drupal 7 projects:
curl -sS https://getcomposer.org/installer | php
php composer.phar create-project drupal-composer/drupal-project:8.x-dev some-dir
cd some-dir
php ../composer.phar require drupal/devel:8.*A Drupal project usually consists of the following:
- Drupal Core
- A number of modules and maybe a base theme downloaded from Drupal.org
- Perhaps even some PHP libraries found on GitHub
- Custom code written by you and your team mates
The most popular approach to assembling these parts is using Drush Make.
Meanwhile the PHP Community has gathered around another dependency manager, Composer. It is even used for managing dependencies for Drupal 8 Core.
This project aims to be a ressource for using Composer to manage Drupal projects with the same advantages as Drush Make but without the tradeoffs regardless of what version of Drupal being used.
To start your first Drupal project with Composer you need to:
- Install Composer.
- Create a
composer.jsonfile in the root of your project with appropriate properties - primarily the Drupal core package and the Drupal.org package repository. To use thecomposer.jsontemplate provided by this project run `composer create-project drupal-composer/drupal-project project-dir --stability dev --no-interaction - Run
composer installfrom your project directory to install Drupal 7. - Run
composer require drupal/some-projectto install a module or theme from Drupal.org.
You should now have a Drupal 7 installation in your project directory and be ready to include other projects from Drupal.org.
The following aims to explain Composer in relation to Drush Make based on the structure of the Drush Make documentation.
Composer has a great introduction and thorough documentation of the composer.json format.
The core version of Drupal to be used with the project is specified using the Composer non-destructive archive installer plugin.
Adding the following package to the repositories and requires sections will download Drupal 7.28 to the root of the Composer project:
{
"repositories": [
{
"type": "package",
"package": {
"name": "drupal/drupal",
"type": "non-destructive-archive-installer",
"version": "7.28",
"dist": {
"url": "http://ftp.drupal.org/files/projects/drupal-7.28.zip",
"type": "zip"
},
"require": {
"azt3k/non-destructive-archive-installer" : "*"
},
"extra": {
"target-dir": ".",
"omit-first-directory": "true"
},
"replace": {
}
}
}
],
"require": {
"azt3k/non-destructive-archive-installer" : "0.2.*",
"drupal/drupal": "7.*"
}
}Using Composer to manage Drupal projects has so far been tested with Drupal 7 projects. It may or may not work for Drupal 6 and 8.
This behavior differs from both Drush Make and standard Composer.
Requiring this package will download Drupal Core as a part of the project and unpack it in the root of the project. Consequently there is no need for recursive make files or the like.
Note that any core module required by contrib projects must be added in the replace section to inform Composer that there is no need to download these separately. This project template includes all core modules in the replace section.
All Drupal projects to be retrieved should be added as dependencies in the format drupal/[module-short_name] and their version in the format [drupal-version].[module-major-version].[module.minor-version]`.
The following will download the Chaos tool suite (ctools) module version 1.4 for Drupal 7.
{
"require": {
"drupal/ctools": "7.1.4"
}
}The module will be placed under sites/all/modules/contrib/.
You can also run php composer.phar require drupal/ctools from the command line in the root directory of the project. This is prompt for any additional information needed and update composer.json accordingly.
Drupal projects are normally not available from the default Composer package repository Packagist. In order to for this to work a custom repository must be added:
{
"repositories": [
{
"type": "composer",
"url": "http://packagist.drupal-composer.org"
}
]
}This repository is generated using the drupal-parse-composer project.
You specify the version of each project using Composer package version constraints.
In this example the following releases of Drupal 7 modules will be downloaded:
- Latest stable minor release of Chaos tool suite 1.x
- Latest stable release of Features
- Latest development release of Views 3.x
{
"require": {
"drupal/ctools": "7.1.*",
"drupal/features": "7.*",
"drupal/views": "7.3-dev"
}
}Patching projects is supported by the Netresearch patches Composer plugin.
To apply a patch to a project a patches section must be added to the extras section of composer.json.
The following will patch the Chaos tool suite version 7.1.4 with this patch:
{
"repositories": [
{
"type": "package",
"package": {
"name": "reload/drupal-composer-project-patches",
"version": "1.0.0",
"type": "patches",
"require": {
"netresearch/composer-patches-plugin": "~1.0"
},
"extra": {
"patches": {
"drupal/ctools": {
"7.1.4": [
{
"title": "Delete not needed element from array in existing node plugin",
"url": "https://drupal.org/files/issues/ctools-deleted-not-needed-element-from-array-in-node-plugin.patch"
}
]
}
}
}
}
}
],
"require": {
"netresearch/composer-patches-plugin": "~1.0",
"reload/drupal-composer-project-patches": "*"
}
}The important parts about a package containing patches are:
- It must have the
patchestype - It must require the
netresearch/composer-patches-pluginpackage - It can contain multiple patches to multiple projects
- The root package should require the patches package
- When adding or removing patches to a package the package version must be updated as well
The plugin supports other options for specifying patches as well.
Patching Drupal Core may not work since Drupal Core is handled using a custom Composer installer.
The plugin does not generate a PATCHES.txt file for each patched project as Drush Make does.
The location of projects can be changed in the installer-paths section of composer.json either by individual project or by type.
{
"extra": {
"installer-paths": {
"sites/all/modules/contrib/{$name}/": ["type:drupal-module"],
"sites/all/themes/{$name}/": ["drupal/zen"]
}
}
}Custom location of packages are handled by the Composer Installers project.
Specifying alternate sources of Drupal projects is not immediatly supported.
One approach to achieving would be to update the Drupal.org packages.json generator to support other updates XML servers than updates.drupal.org, custom vendor names and add the resulting packages.json to the repositories section.
To specify the type of a Drupal project set the package type to one of the types supported by the Composer Installers project. This includes drupal-module and drupal-theme.
Note that for this to work the Composer package for the project must also require "composer/installers": "~1.0".
Projects can be placed in specific directories using the installer-paths section. See Subdir.
Composer does not support specifying custom paths for translations.
Composer does not support specifying custom translation servers.
Composer does not have an option to specify that a package should be installed in a non-empty directory.
Composer does not handle handle translations.
To download a project which is not on Drupal.org or a Composer package then define it as a custom package repository and add it as a dependency.
This method supports version constrol checkouts from custom branches or tags as well as file downloads.
Non-Drupal non-Composer libraries can be retrieved by specifying them as custom Package repository. See Project download options.
Example downloading jQuery UI 1.10.4:
{
"repositories": [
{
"type": "package",
"package": {
"name": "jquery/jqueryui",
"version": "1.10.4",
"type": "drupal-library",
"dist": {
"url": "http://jqueryui.com/resources/download/jquery-ui-1.10.4.zip",
"type": "zip"
},
"require": {
"composer/installers": "~1.0"
}
}
}
],
"require": {
"jquery/jquery.ui": "1.10.4"
}
}A different package type is introduced here: drupal-library. This allows Composer Installer to handle library placement different compared to modules and themes.
Libraries are defined as Composer packages and thus support the same options as Drupal projects and Composer packages in gneeral.
Libraries can be placed in specific directories using the installer-paths section. See Subdir.
Composer uses dependencies as includes. If a dependency has dependencies on its own and specifies these in its' composer.json file then these dependencies will be installed as well. Note that a Composer package does not have to contain any actual code - this project is an example of just that!
If the purpose of including additional files is to define packages then Composer has different option for including package defitions through the repositories section.
Composer does not have the concept of user-defined default values for packages.
Composer Installer does support setting a standard directory for all packages of a specific type e.g. modules. See Subdir.
Composer does not support overriding individual properties for a package.
One approach to changing properties is to fork the package, update the composer.json for the package accordingly and add a new repository pointing to the fork in the root composer.json.
Packages overriding the Drupal projects repository should be placed before this repository due to the over in which Composer looks for packages.
Composer resolves dependencies and a range of other properties from composer.json files recursively.
A few properties are only defined by the root package - the composer.json for the project.
Composer does not support generating a composer.json file form an existing project.
Drush Make has its own problems which makes it difficult to work with e.g.:
- Multiple
.makefiles to support downloading Drupal Core with custom code - Tricky rebuild process leading to custom workarounds
- Build process makes it slow to use developer tools like git bisect.
Also Drush Make is a tool primarily built for Drupal. The PHP community has matured a lot lately. Using Composer means using the same tool as the rest of the community of the makes it easy to use other libraries with a Drupal project.
It is time to get off the island!
Composer recommends no. They provide argumentation against but also workrounds if a project decides to do it anyway.
Using Composer to manage a Drupal project would not be possible without the work of others:
- Non-destructive archive installer used to install Drupal Core.
- Composer installers used to specify custom location of packages.
- Netresearch patches plugin for applying patches to Composer projects.