Recommended Workflows

Common workflows for working with Composer Patches on a team.

Initial setup

The plugin can safely be installed as part of initial project setup, even if you don’t have any patches to apply right away. A patches.lock.json will still be written, but it will be empty.

Add a patch to your project

Define a patch in your composer.json or your external patches file (either will work by default, but choose the appropriate place based on how your project is configured).
Run composer patches-relock to regenerate patches.lock.json with your new patch.
Run composer patches-repatch to delete patched dependencies and reinstall them with any defined patches

Running `composer patches-repatch` will delete data

Ensure that you don’t have any unsaved changes in any patched dependencies in your project.
If your patch definition was added to composer.json, run composer update --lock to update the content hash in composer.lock.
Commit any related changes to your external patches file (if configured), composer.json, composer.lock, and patches.lock.json.

Apply patches added to the project by someone else

If you have an existing copy of the project and you’re updating it to include someone else’s changes:

Pull changes from your project’s version control system.
Run composer patches-repatch

Running `composer patches-repatch` will delete data

Ensure that you don’t have any unsaved changes in any patched dependencies in your project.

If you’re installing the project from scratch:

Clone the project
Run composer install

Remove a patch

Delete the patch definition from your composer.json or external patches file.
Run composer patches-relock to regenerate patches.lock.json with your new patch.
Manually delete the dependency that you removed a patch from (the location of the dependency will vary by project, but a good starting point is to look in the vendor/ directory).
Run composer patches-repatch to delete patched dependencies and reinstall them with any defined patches

Running `composer patches-repatch` will delete data

Ensure that you don’t have any unsaved changes in any patched dependencies in your project.
If your patch definition was removed from composer.json, run composer update --lock to update the content hash in composer.lock.
Commit any related changes to your external patches file (if configured), composer.json, composer.lock, and patches.lock.json.