The Composer Patches (cweagans/composer-patches) library makes patching projects easy when using Composer. Simply add a patches key to the extra section of your composer.json file and run composer install or composer update.

However, with the update to Composer Patches 2.0, the workflow has changed. If you aren’t aware of the new mechanics and update your dependencies to the new version, when you add a new patch it will silently fail. This can be confusing if you are used to simply adding patches in composer.json and updating dependencies to apply them.

The New Patches Lock File

Composer Patches 2.0 introduced a new patch locking file: patches.lock.json.  Composer patches generates this file the first time you run composer install (or when updating to 2.0). After it exists, it will be the the single source of truth for all patches (similar to the way other lock files work). Manually adding a new patch to composer.json will no longer apply automatically even when running update or install commands. 

This is a common frustration if you are not expecting this behavior with the update:

1. You install the project with no patches defined.
2. Composer generates patches.lock.json with an empty list.
3. You later add a new patch to composer.json.
4. You reinstall dependencies expecting the patch to apply with either composer update or composer install.
5. Composer continues using the locked (empty) patch set.
6. The patch is not applied.
7. You tear out your hair wondering what you did wrong.

Updating the New Patches Lock File

Fortunately, the solution is easy once you know what to expect. Composer Patches 2.0 provides two new commands specifically for updating the patches lock file:

composer patches-relock     # Regenerate patches.lock.json
composer patches-repatch    # Reinstall patched packages 

This forces Composer to:

• Re-read the patch definitions from composer.json
• Update the patches lock file to match
• Reinstall packages with the patch applied

If you want a hard reset, you can also temporarily delete patches.lock.json and run a standard install which will regenerate the file.

Use Composer’s Diagnostics

Composer Patches 2.0 also includes a new health check command: 

composer patches-doctor

The doctor command will flag:

• Resolver issues
• Missing patch definitions
• Invalid URLs
• Disabled patching

It’s the fastest way to validate environment compatibility.

Summary

If you’ve been wrestling with “composer patches not working”, patches silently failing, or updates that don’t reflect the changes you expect, the steps outlined here will get you back on track. The introduction of patches.lock.json is a solid improvement for reproducibility, but only once you know how to work with it.