Patching and the Composer Workflow

Patch Factory

Let’s face it—nobody likes to rely on patches. A project is much easier to maintain when it is using standard versions of all of its dependencies. Without patches, a project can be kept up to date simply by running composer update

Unfortunately, when working with Open Source software, it sometimes comes to pass that a project needs to apply a critical bug fix that the maintainer of the affected dependency has not yet rolled into a stable release. In this instance, it becomes necessary to apply a patch. When necessity demands patching, it is important to choose a good patch manager, to keep the process as convenient as possible for everyone involved.

There are a number of custom composer installers that support a patch workflow to choose from. The best of these is cweagans/composer-patches. Instructions on using this project are available in its GitHub repository.

[Related] Fixing Shortcomings in the Composer Update Process

Build Consistency Is Maintained

Composer patch managers work by using a composer post-project-install hook to alter the project code after composer installs it. The problem with this hook is that it only runs when a project is installed. One of the main advantages of the cweagans patch manager is that it will force a project’s patches to be re-applied whenever the patch information changes, even if there has been no change to the component being patched. 

This behavior is particularly important in a multi-developer environment. If one developer adds or changes a patch URL, and commits the change to the source code repository, other team members can rely on the fact that composer install will produce a consistent results after they update their sources. With other patch managers, you run the risk of missing patch updates if you do not do a clean build every time you pull code.

Patches are Handled Recursively

For those who are maintaining installation profiles that are used in other projects, cweagans/composer-patches provides the added benefit of collecting patches from all dependencies, as if they were listed in the root composer.json file. This allows the installation profile to maintain the patches needed for its modules in its composer.json, in the same way that patches can be recursively specified in Drush make files.

A Record of Patches Applied Is Kept

Finally, cweagans/composer-patches also writes a PATCHES.txt file in each project that it modifies, just like Drush make does. This bit of standardization is good practice to help those inspecting the build results to know how each dependency has been modified, if in fact it has been. Other patch managers do not provide this.

These benefits makes the cweagans/composer-patches patch manager much more convenient to use than any of the alternatives. If you are using a patch manager from any other source, you should switch to cweagans/composer-patches; it is now recommended as the standard patch manager to use by the Drupal Composer working group. For more information, see the page “Composer in relation to Drush Make” on

Topics Development, Drupal Planet, Drupal