Detailed guide on how to use the advanced configuration options of the plugin to define patches.
In case there's a need to define a patch that targets multiple packages within a single patch file, alternative patch definition format is recommended:
{
"extra": {
"patches": {
"*": {
"fixes for multiple packages (packages explicitly mentioned)": {
"source": "example/bundled-fixes.patch",
"targets": [
"some/module",
"other/module"
]
},
"same as above, but targets are auto-resolved from file contents": {
"source": "example/bundled-fixes.patch"
}
}
}
}
}Where the example/bundle.patch content would have file paths defined in following manner:
--- some/module/Models/Example.php.org
+++ some/module/Models/Example.php
@@ -31,7 +31,7 @@
*/
protected function someFunction($someArg)
{
- $var1 = 123;
+ $var1 = 456;
/**
* rest of the logic of the function
*/
--- other/module/Logic.php.org
+++ other/module/Logic.php
@@ -67,7 +67,7 @@
*/
protected function otherFunction()
{
- $label = 'old';
+ $label = 'new';
/**
* some implementation
*/Note that if you plan to use bundled patches whilst also using patches-base, the following approach could be used:
{
"extra": {
"patches-base": {
"default": "patches/{{VendorName}}_{{(Magento2|Module)ModuleName}}/{{file}}/version-{{version}}.patch",
"*": "patches/Bundled/{{file}}/version-{{version}}.patch"
}
}
}The first dependency version will be used for the bundled patches {{version}} value.
In case it's important to apply certain patches in a certain order, use before/after directives. Note that you can use partial names (instead of using full path) and wildcards to target patches.
{
"extra": {
"patches": {
"targeted/package": {
"will be applied after my/other-file.patch": {
"source": "my/file.patch",
"after": "other-file"
},
"some change to another targeted package": {
"source": "my/other-file.patch"
}
}
}
}
}
Multiple dependencies can be defined when after/before value given as an array.
Patches can be defined to be only applied when certain platform constraint requirements are met.
{
"extra": {
"patches": {
"targeted/package": {
"applies only when running on system that has runs PHP with high enough version": {
"source": "example/other-fix.patch",
"depends": {
"php": ">=7.1.0"
}
}
}
}
}
}Base path variables allow developers to shorten the definition of patch paths which might become cumbersome and repetitive.
{
"extra": {
"patches-base": "patches/{{VendorName}}_{{ModuleName}}/{{version}}/{{file}}",
"patches": {
"some/package-name": {
"Fix: back-port for some important fix": {
"source": "important-fix.patch",
"version": [
">=v2.7.0 <v2.7.1",
">=v2.7.1 <v2.8.33",
">=v2.8.33 <v3.0.0"
]
}
}
}
}
}
The following will use the version information and targeted package name to generate source paths:
<owner-root>/patches/Some_PackageName/v2.7.0/important-fix.patch
<owner-root>/patches/Some_PackageName/v2.7.1/important-fix.patch
<owner-root>/patches/Some_PackageName/v2.8.33/important-fix.patch
The variables can also have partial value strip rules to shorten the names.
{
"extra": {
"patches-base": "patches/{{VendorName}}_{{(Package|Other)ModuleName}}/{{version}}/{{file}}",
"patches": {
"some/package-name": {
"Fix: back-port for some important fix": {
"source": "important-fix.patch",
"version": [
">=v2.7.0 <v2.7.1"
]
}
}
}
}
}
The following little change will result the patches to be taken from following paths
<owner-root>/patches/Some_Name/v2.7.0/important-fix.patch
These rules will apply in the boundaries of the composer.json where the base path rule was defined.
If version is not known (not defined as a restriction), but is used in patches-base definition, then the value "0.0.0" will be used.
In case patch comment is just a repetition of what the path file name says, the following can be used:
{
"extra": {
"patches-base": "patches/{{VendorName}}_{{(Package|Other)ModuleName}}/{{version}}/{{(feature|fix)label}}",
"patches": {
"some/package-name": {
"Fix: other-fix.patch": "1.2.3",
"Fix: back-port-for-some-important-fix.patch": [
">=2.7.0 <2.7.1",
">=2.8.33 <3.0.0"
]
}
}
}
}
The following little change will result the patches to be taken from following paths
<owner-root>/patches/Some_Name/1.2.3/other-fix.patch
<owner-root>/patches/Some_Name/2.7.0/back-port-for-some-important-fix.patch
<owner-root>/patches/Some_Name/2.8.33/back-port-for-some-important-fix.patch
Note the value-strip rules that have been defined for label which take care of not including "Fix: " prefix when using label as filename.
By default, the patcher will try to apply the patch with several path stripping options - in some cases this is not something that one wants to allow - for example: if the patch is in full extent just creating new files, it might end up creating them to wrong directories.
In some cases, some patches might have unconventional path definitions that derive from other project patches. Rather than changing the global settings, it's possible to define custom ones for just one patch.
{
"extra": {
"patches": {
"targeted/package": {
"Some patch description": {
"source": "example.patch",
"level": "0"
}
}
}
}
}In case you would like a patch only to apply when working with some package directly (where the package itself is ROOT package), a special flag can be defined to indicate such a thing.
{
"extra": {
"patches": {
"targeted/package": {
"Some patch description": {
"source": "example.patch",
"local": true
}
}
}
}
}Note that this is somewhat conflicting on how Composer deals with this where the case with composer is that when you declare something as require-dev, it'll only get installed when the package is ROOT.
In the context of this plugin, this flag will allow similar situation to be achieved:
- When installing the owner of the patch as a dependency: patch is not applied
- When cloning the owner separately and running composer install: patch will be applied
In case there's a need to temporarily skip patches which is usually the case when going through maintenance or upgrade of the underlying project's framework, a skip flag can be used to pass over certain declaration lines.
{
"extra": {
"patches": {
"targeted/package": {
"This patch will be ignored": "example.patch#skip"
}
}
}
}Note that in case patches-base is used, the #skip flag will be naturally be added to the end of the resolve patch path.
In cases where there's a need to apply a patch on a file that is mapped to the project root or vendor bin root, a patch applier working directory resolver mode can be defined (which technically would mean that the applier works off of custom root/directory when applying certain patch):
{
"extra": {
"patches": {
"targeted/package": {
"This patch downloads a file to project root": {
"source": "example.patch",
"cwd": "project"
}
}
}
}
}This will tell the patch applier to: (a) reset targeted/package; (b) apply 'example.patch' in project root. That means that the targeted file paths within example.patch should also target files relative to project root.
Available cwd options:
- install - (default) uses package install folder
- vendor - uses vendor path
- project - uses project path
- autoload - uses path that the package has configured as autoloader root (will use first path when multiple paths defined). Falls back to using 'install' path when autoloader config not found.
This is particularly useful when targeted/package introduces it's own file mapper mechanism that is
triggered by composer events (which might mean that files are copied away from the re-install package before
patch applier kicks in).
In case all patches from certain owner package (the package where the patches originate from) require same setup for every one of them - a shared configuration could be defined (which will be used for all the patches).
{
"extra": {
"patches": {
"_config": {
"cwd": "autoload"
},
"targeted/package": {
"_config": {
"version": ">2.0.0"
},
"This patch downloads a file to project root": "example.patch",
"More information about the patch": "another.patch"
}
}
}
}This particular example will allow you to skip from having to define the exact same thing for all the patches that target targeted/package and just define it once under the key _config. The information put there will be made available for all the patches.
Note that different config items will be merged (lower scope overwriting the higher) so that what actually applies in this case for all the patches is:
{
"cwd": "autoload",
"version": ">2.0.0"
}If you have patches tucked away under different patches definitions files, then the config will not be shared between them (will apply only to the patches in that particular patches definition file).
In case some patches that are defined in packages have to be excluded from the project (project has custom versions of the files, conflicts with other patches, etc), exclusions records can be defined in the project's composer.json:
{
"extra": {
"patches-exclude": {
"patch/owner": [
"some/path/example.patch",
"example.patch",
"example",
"ex*ple"
]
}
}
}Note that all of the exclusion listed above are valid ways of excluding patches.
Will exclude the a patch that was defined in a package in following (or similar) manner ...
{
"name": "patch/owner",
"extra": {
"patches": {
"targeted/package": {
"fix description": "some/path/example.patch"
}
}
}
}The important part to note here is to remember that exclusion ignores patch target and focuses on the owner instead.
In case user wants to add extra comments to patch declaration file, any key that start with "_" can be used. Works on any level of the patch declaration.
{
"_comment": "This patch file should hold patches that make world a better place",
"whole/world": {
"_excuse": "I really need this one",
"Fix: get closer to ending poverty": "patches/provide-affordable-education.patch"
},
"_note": "This is another comment"
}