For most Drupal projects, patches are inevitable. It’s how we, in the Drupal community, share code. If that scares you, don’t worry-- the community is working hard to move to a pull/merge request workflow. Due to the collaborative nature of Drupal as a thriving open source community and the always growing ecosystem of contrib modules, patches are the ever-evolving glue that can hold a site together.
Before Drupal 8, you may have seen projects use drush make which is a Drupal specific solution. As part of the “get off the island” movement, Drupal adopted existing dependency manager Composer. Composer does a decent job alleviating the headaches of managing several sites with different dependencies. However, out of the box Composer will revert patched core files and contrib modules and it is for that reason composer-patches project was created. In this blog post, we are going to review how to set up composer-patches for a composer managed project and how to specify local or remote hosted patches.
The setup
In your favorite command line tool, you will want to add the composer-patches project:
composer require cweagans/composer-patches:~1.0 --update-with-dependencies
With this small change, your project is now set up for success because composer can manage your patches.
Local patches
Sometimes you will find that you need patch contrib or core specifically for your project and therefore the patch exists locally. Composer-patches can apply that patch for you, we just need to tell it where it is. Let’s look at an example project that has core patch applied and saved locally in the project root directory ‘patches/core-invalid-config-structures.patch’: ...
"extra": {
"patches": {
"drupal/core": {
"Core Invalid config structures ":"patches/core-invalid-config-structures.patch"
}
}
}
In your composer.json, you will want to add an “extra” section if it doesn’t already exist. Composer-patches will take the packages listed in “patches” and try to apply any listed patches. In our above example, the package we are patching is “drupal/core”. Patches are declared as follows:
“Patch description”: “path to patch file”
This information will be printed on the command line while composer tries to update the package which makes it important to summarize the patches purpose well. If you would like to see what this looks like in the wild, take a look at our distribution Rain which leverages a couple of contrib patches.
After manually updating composer.json, it is always a good idea to run composer validate to confirm the json syntax is right. If you get the green success message run composer update drupal/[projectname], e.g. composer update drupal/core to have the patch applied.
You will know that the patch is applied based on the output:
As you can see, the package getting patched is removed, added back and the patch is applied.
Note: Sometimes I feel like I have to give composer a nudge, always feel comfortable deleting /core, /vendor, or /modules/contrib, but if you delete composer.lock know that your dependencies could update based off your constraints. Composer.json tracks our package dependencies at certain version constraints while composer.lock is the recipe of computed versions based off those constraints. I have found myself running the following:
rm -rf core && rm -rf modules/contrib && rm -rf vendor
composer install
Remote Patches
When possible we should open issues on Drupal.org and post patches there. That way, the community can work together to solve a problem and usually you’ll get a more reliable, lasting solution. Think about it this way - would you rather only you or your team review a critical patch to your project or hundreds of developers?
To make composer-patches grab a remote patch make the following changes: ...
"extra": {
"patches": {
"drupal/core": {
"#2925890-10: Invalid config structures ":"https://www.drupal.org/files/issues/2018-09-26/2925890-10.patch"
}
}
}
The only change here is rather than the path to the local patch, we have substituted it for the URL the patch. This will have a similar success message when applied correctly:
Tips
So far, I’ve shown you how to get going with composer-patches project but there are a lot of settings/plugins that can elevate your project. A feature I turn on for almost all sites is exit on patch failure because it is a big deal when a patch fails. If you too want to turn this feature on, add the following line to your “extras” section in your composer.json:
"composer-exit-on-patch-failure": true,
I have also found it helpful to add a link back to the original issue in the composer.json patch declaration. Imagine working on a release and one of your patches fail but the only reference you have to the issue is the patch file url? It is times like these that a link to the issue can make your day. If we made the same change to our example before, it would look like the following:
"drupal/core": {
"#2925890-10: Invalid config structures (https://www.drupal.org/project/drupal/issues/2925890)" : "https://www.drupal.org/files/issues/2018-09-26/2925890-10.patch"
}
Conclusion
Composer-patches is a critical package to any Drupal project managed by Composer. In this blog I showed you how to get started with the project and some of the tips and tricks I’ve learned along the way. How does your team user composer-packages? Do you have a favorite setting that I didn’t mention? Feel free to drop a comment and share what works for you and your team.