Managing patches with Composer

All modifications to contributed projects and most modifications to Drupal core should be performed using patches.

Applying patches

Patches can be applied by referencing them in the composer.json file, in the following format. cweagans/composer-patches can then be used to apply the patches on any subsequent website builds.

Patch information should be specified in the JSON array in accordance with the following schema:

"extra": {
  "patches": {
    "drupal/core": {
      "Ignore front end vendor folders to improve directory search performance": "https://www.drupal.org/files/issues/ignore_front_end_vendor-2329453-116.patch",
      "My custom local patch": "./patches/drupal/some_patch-1234-1.patch"
    }
  }
},

Note: When a package is patched, it s advisable to pin it to a specific version to avoid downloading an updated version that could introduce a patch conflict.

After modifying the composer.json file, run composer update VENDOR_NAME/PACKAGE_NAME, replacing VENDOR_NAME/PACKAGE_NAME with the name of the patched dependency. For example:

composer update drupal/core

This will apply the patch and update composer.lock. Commit the modified composer.json and composer.lock files.

You can also apply the patch by running composer update. This, however, will update all the project's dependencies, which may not be desired.

Storing patches

Patches that can be contributed on Drupal.org should be contributed there. Be sure to follow Drupal.org's patch naming conventions when creating patches.

Patches that cannot be contributed publicly are extremely rare. In the unlikely event that such a change must be committed, all project-specific patches should reside in this directory. This ensures one consistent place for patches and avoids accidental patch deletion.

Patches should be stored in sub-directories based on the project name being patched.

Examples

• /patches/drupal/some_patch-1234-1.patch
• /patches/ctools/another_patch_name-9876-12.patch

Gotchas

Composer can only patch files that are distributed with Composer packages. This means that certain files (such as the Drupal core .htaccess and robots.txt) cannot be easily patched via Composer. These files are not included in the Drupal core Composer package. Notably, Drupal Scaffold individually creates these files on updates.

To modify .htaccess and other un-patchable root files, modify the file in place, commit it to Git, and then make the following change in the composer.json file:

"extra": {
  "drupal-scaffold": {
    "excludes": [
      ".htaccess"
    ]
  }
},

The downside is that you will need to apply Drupal core updates to these excluded files on your own.

Alternately, you could leverage the post-drupal-scaffold-cmd script hook to apply patches after Drupal Scaffold is finished. See this composer-patches issue for more details.

Also note that there is an issue in the Drupal packaging system that makes it difficult to patch module and theme .info.yml files. If you have trouble applying a patch that modifies an info file, see this issue for a description and workaround.