Skip to content

Commit 995abee

Browse files
copitzcopitz
committed
Updated documentation (fixes #12)
1 parent 2361e53 commit 995abee

File tree

1 file changed

+133
-92
lines changed

1 file changed

+133
-92
lines changed

‎README.md

+133-92
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,81 @@
11
# composer-patches-plugin
22

3-
Plugin for composer to apply patches onto dependencies.
3+
This plugin allows you to provide patches for any package from any package.
44

5-
Slides: http://de.slideshare.net/christianopitz/distributed-patching-with-composer
5+
If you don't want a patch package outside the root package, consider providing it as package in the [repositories key](https://getcomposer.org/doc/04-schema.md#repositories)
66

7-
## Providing patches
7+
```json
8+
{
9+
"name": "vendor/package",
10+
"type": "project",
11+
"repositories": [
12+
{
13+
"type": "package",
14+
"package": {
15+
"type": "metapackage",
16+
"name": "vendor/package-patches",
17+
"version": "1.0.0",
18+
"require": {
19+
"netresearch/composer-patches-plugin": "~1.0"
20+
},
21+
"extra": {
22+
"patches": {
23+
"vendor/name": [
24+
{
25+
"url": "https://my-domain.com/path/to/my.patch"
26+
}
27+
]
28+
}
29+
}
30+
}
31+
}
32+
],
33+
"require": {
34+
"vendor/package-patches": "~1.0"
35+
}
36+
}
37+
```
38+
39+
See this presentation for the original idea of this plugin: http://de.slideshare.net/christianopitz/distributed-patching-with-composer
840

9-
You can provide the patches in any package through the extra object (you are free but don't have to bundle your patches in "patches" packages):
41+
## Patch properties
42+
43+
Key | Description | Required
44+
--- | --- | ---
45+
``url`` | The url or path to the patch | ✓
46+
``title`` | Title to display when applying or reverting the patch |
47+
``args`` | string, which will be added to the patch command |
48+
``sha1`` | SHA1 checksum of the patch contents for security check - when given the patches actual checksum and this value are compared and if they don't match an exception will be thrown |
49+
50+
You may provide patches per package and optionally by version constraints:
51+
52+
## Provide patches by package only
53+
```json
54+
{
55+
"name": "netresearch/typo3-patches",
56+
"version": "1.0.0",
57+
"type": "metapackage",
58+
"require": {
59+
"netresearch/composer-patches-plugin": "~1.0"
60+
},
61+
"extra": {
62+
"patches": {
63+
"typo3/cms": [
64+
{
65+
"title": "[FEATURE] Allow registration of different login forms",
66+
"url": "https://git.typo3.org/Packages/TYPO3.CMS.git/patch/32f331fead9c7aa50d9248c54e3c0af75d793539"
67+
},
68+
{
69+
"title": "[PATCH] [BUGFIX] Flexform \"required\" on input fields applies to last field only",
70+
"url": "https://git.typo3.org/Packages/TYPO3.CMS.git/patch/a48f8b0dae11ce7246eff43132d986bccf55b786"
71+
}
72+
]
73+
}
74+
}
75+
}
76+
```
77+
78+
## Provide patches by package and versions or version constraints
1079

1180
***
1281
composer.json:
@@ -21,81 +90,86 @@ composer.json:
2190
"extra": {
2291
"patches": {
2392
"typo3/cms": {
24-
"6.2.0-beta1": {
25-
"32f331fead9c7aa50d9248c54e3c0af75d793539": {
93+
"6.2.0-beta1": [
94+
{
2695
"title": "[FEATURE] Allow registration of different login forms",
2796
"url": "https://git.typo3.org/Packages/TYPO3.CMS.git/patch/32f331fead9c7aa50d9248c54e3c0af75d793539"
2897
},
29-
"a48f8b0dae11ce7246eff43132d986bccf55b786": {
98+
{
3099
"title": "[PATCH] [BUGFIX] Flexform \"required\" on input fields applies to last field only",
31100
"url": "https://git.typo3.org/Packages/TYPO3.CMS.git/patch/a48f8b0dae11ce7246eff43132d986bccf55b786"
32101
}
33-
},
34-
"6.2.0-beta2": {
35-
"a48f8b0dae11ce7246eff43132d986bccf55b786": {
102+
],
103+
"6.2.0-beta2": [
104+
{
36105
"title": "[PATCH] [BUGFIX] Flexform \"required\" on input fields applies to last field only",
37106
"url": "https://git.typo3.org/Packages/TYPO3.CMS.git/patch/a48f8b0dae11ce7246eff43132d986bccf55b786"
38107
}
39-
},
40-
"6.2.0-beta3": {
41-
"a48f8b0dae11ce7246eff43132d986bccf55b786": {
42-
"title": "[PATCH] [BUGFIX] Flexform \"required\" on input fields applies to last field only",
43-
"url": "https://git.typo3.org/Packages/TYPO3.CMS.git/patch/a48f8b0dae11ce7246eff43132d986bccf55b786"
108+
],
109+
"6.2.*": [
110+
{
111+
"title": "[BUGFIX] Ignore dependencies on non typo3-cms-extension",
112+
"url": "https://git.typo3.org/Packages/TYPO3.CMS.git/patch/9fe856ac96e6a53fef8277f36a4a80bace6f0ae9",
113+
"sha1": "b56a1c47a67d1596c0bd8270e61c44f8911af425"
44114
}
45-
}
115+
]
46116
}
47117
}
48118
}
49119
}
50120
```
51121

52-
* The keys of the patches are the its IDs, which are only used for console output - so, basically you can use any string for that.
53-
* Each patch requires a ``title`` and an ``url`` - additionally it can have an ``args`` string, which will be added to the patch command.
54-
* You can put any part of the patches object into another JSON and load it via an URL (or a path):
55-
* composer.json:
56-
```json
57-
{
58-
"name": "netresearch/typo3-patches",
59-
"version": "1.0.0",
60-
"type": "metapackage",
61-
"require": {
62-
"netresearch/composer-patches-plugin": "~1.0"
63-
},
64-
"extra": {
65-
"patches": {
66-
"typo3/cms": "http://example.com/typo3-patches.json"
67-
}
122+
**Note**: *When multiple version constraints match the version of the target package, all of the matching patches will be applied (canonicalized by theyr checksums, so no duplicates should occure).*
123+
124+
## Provide patches from URLs or paths
125+
126+
You can put any part of the patches object into another JSON and load it via an URL (or a path):
127+
128+
composer.json:
129+
```json
130+
{
131+
"name": "netresearch/typo3-patches",
132+
"version": "1.0.0",
133+
"type": "metapackage",
134+
"require": {
135+
"netresearch/composer-patches-plugin": "~1.0"
136+
},
137+
"extra": {
138+
"patches": {
139+
"typo3/cms": "http://example.com/typo3-patches.json"
68140
}
69141
}
70-
```
71-
72-
* http://example.com/typo3-patches.json
73-
```json
74-
{
75-
"6.2.0-beta1": {
76-
"32f331fead9c7aa50d9248c54e3c0af75d793539": {
77-
"title": "[FEATURE] Allow registration of different login forms",
78-
"url": "https://git.typo3.org/Packages/TYPO3.CMS.git/patch/32f331fead9c7aa50d9248c54e3c0af75d793539"
79-
},
80-
"a48f8b0dae11ce7246eff43132d986bccf55b786 ": {
81-
"title": "[PATCH] [BUGFIX] Flexform \"required\" on input fields applies to last field only",
82-
"url": "https://git.typo3.org/Packages/TYPO3.CMS.git/patch/a48f8b0dae11ce7246eff43132d986bccf55b786"
83-
}
84-
},
85-
"6.2.0-beta2": {
86-
"a48f8b0dae11ce7246eff43132d986bccf55b786 ": {
87-
"title": "[PATCH] [BUGFIX] Flexform \"required\" on input fields applies to last field only",
88-
"url": "https://git.typo3.org/Packages/TYPO3.CMS.git/patch/a48f8b0dae11ce7246eff43132d986bccf55b786"
89-
}
142+
}
143+
```
144+
145+
http://example.com/typo3-patches.json
146+
```json
147+
{
148+
"6.2.0-beta1": [
149+
{
150+
"title": "[FEATURE] Allow registration of different login forms",
151+
"url": "https://git.typo3.org/Packages/TYPO3.CMS.git/patch/32f331fead9c7aa50d9248c54e3c0af75d793539"
90152
},
91-
"6.2.0-beta3": {
92-
"a48f8b0dae11ce7246eff43132d986bccf55b786 ": {
93-
"title": "[PATCH] [BUGFIX] Flexform \"required\" on input fields applies to last field only",
94-
"url": "https://git.typo3.org/Packages/TYPO3.CMS.git/patch/a48f8b0dae11ce7246eff43132d986bccf55b786"
95-
}
153+
{
154+
"title": "[PATCH] [BUGFIX] Flexform \"required\" on input fields applies to last field only",
155+
"url": "https://git.typo3.org/Packages/TYPO3.CMS.git/patch/a48f8b0dae11ce7246eff43132d986bccf55b786"
96156
}
97-
}
98-
```
157+
],
158+
"6.2.0-beta2": [
159+
{
160+
"title": "[PATCH] [BUGFIX] Flexform \"required\" on input fields applies to last field only",
161+
"url": "https://git.typo3.org/Packages/TYPO3.CMS.git/patch/a48f8b0dae11ce7246eff43132d986bccf55b786"
162+
}
163+
],
164+
"6.2.*": [
165+
{
166+
"title": "[BUGFIX] Ignore dependencies on non typo3-cms-extension",
167+
"url": "https://git.typo3.org/Packages/TYPO3.CMS.git/patch/9fe856ac96e6a53fef8277f36a4a80bace6f0ae9",
168+
"sha1": "b56a1c47a67d1596c0bd8270e61c44f8911af425"
169+
}
170+
]
171+
}
172+
```
99173

100174
## Requiring the patches:
101175
just require the package with the patches.
@@ -112,36 +186,3 @@ just require the package with the patches.
112186
}
113187
}
114188
```
115-
116-
If you don't want a patch package outside the root package, consider providing it as package in the [repositories key](https://getcomposer.org/doc/04-schema.md#repositories)
117-
118-
```json
119-
{
120-
"name": "vendor/package",
121-
"type": "project",
122-
"repositories": [
123-
{
124-
"type": "package",
125-
"package": {
126-
"name": "vendor/package-patches",
127-
"version": "1.0.0",
128-
"type": "metapackage",
129-
"extra": {
130-
"patches": {
131-
"vendor/name": {
132-
"1.2.3": [
133-
{
134-
"url": "https://my-domain.com/path/to/my.patch"
135-
}
136-
]
137-
}
138-
}
139-
}
140-
}
141-
}
142-
],
143-
"require": {
144-
"vendor/package-patches": "~1.0"
145-
}
146-
}
147-
```

0 commit comments

Comments
 (0)