How to simply apply patches with Composer

Actually nobody wants to patch code. Unfortunately it is often necessary because mistakes even sneak into stable software versions. And when it comes to security holes that have to be closed quickly or errors that need to be fixed as fast as possible, waiting for a troubleshooting in one of the next releases often takes too long.

Patches have many disadvantages. They have to be managed. Once a third-party extension or a core has been modified, a simple update is no longer possible. The changed code must be carried along. Sometimes a fork is the solution, but when it comes to updates it is not possible to do it without a lot of effort. And if the patch is poorly documented or not documented at all, the patch may get lost and in the worst case has to be found again.

Cameron Eagans has released composer-patches a slim composer package for such cases that makes it easy to deploy patches for Composer packages. With the command

composer-patches is applied to the project and the composer.json. The patches can be managed in two ways. They can be configured directly in the composer.json.

If the composer.json should not be overloaded by the configurations, an external file is available as alternative to define the patches. Below this file is called composer.patches.json. In composer.json only the reference to this file is stored.

The file composer.patches.json contains the individual patches and the associated patch file.

Instead of a patch file, as used in the following, a link to the external patch file can be used.

Since one of our customers could not see any content in the frontend after an update to TYPO3 version 8.6.1, we went to search for the track. It turned out that a bug in the core was the reason: styles.content.get not available in FSC anymore. A short time later a patch was available on the TYPO3 review server: Make styles.content.get available after major FSC rewrite.

In order not to be dependent on the next TYPO3 version and still to be able to work on the current version, we decided to patch the core using composer-patches. The composer.patches.json file for this project contains a description of the error and a link to the patch that is used.

This ensures that the patch is used when composer install is called, and each developer can understand why the patch is necessary. In addition, the configuration is versioned with the project. The patch file itself can not be attracted via a link, since composer-patches unfortunately can't handle neither the TYPO3 provided patch files in Base64 nor archives.

The extracted file from the patch file archive (3307a5d.diff.zip) of TYPO3 is therefore in a patches folder within the project. This avoids additional dependencies on the external TYPO3 review server.

When you call composer install, the patch is inserted.

The configuration in the composer.patches.json therefore contains a link as a patch source.

When you call composer install, the patch is inserted.

If you can't avoid a patch, the work with tools like composer-patches is highly recommended.The disadvantages remain within a controllable framework and the overview of the patches in the project is preserved. If the configuration for the patches is given a clean description and thus an implicit documentation, the likelihood that the knowledge about the patch will get lost is very low, and also new colleagues immediately will have an insight. By the versioning of the patch files and the automation with Composer the effort to carry the patch in the project is reduced a lot.