Skip to content

Update readme with more information regarding v2 #53

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
M-arcus wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Update readme with more information regarding v2 #53

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8d0019e
Update readme with more information regarding v2
M-arcus Jan 8, 2026
f2fe48a
Keep br tags
M-arcus Jan 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
68 changes: 46 additions & 22 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,14 +13,10 @@ composer require symplify/vendor-patches --dev
composer require cweagans/composer-patches
```

<br>

Copy link
Member

@TomasVotruba TomasVotruba Jan 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please keep these

Copy link
Contributor Author

@M-arcus M-arcus Jan 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Re-added them, I thought they were leftover HTML tags in a markdown file

## Usage

How to create [a patch for a file in `/vendor`](https://tomasvotruba.com/blog/2020/07/02/how-to-patch-package-in-vendor-yet-allow-its-updates/)?

<br>

### 1. Create a Copy of `/vendor` file you Want To Change with `*.old` Suffix

For example, if you edit:
Expand All @@ -31,8 +27,6 @@ vendor/nette/di/src/DI/Extensions/InjectExtension.php
vendor/nette/di/src/DI/Extensions/InjectExtension.php.old
```

<br>

### 2. Open the original file and change the lines you need:

```diff
Expand All @@ -45,7 +39,7 @@ vendor/nette/di/src/DI/Extensions/InjectExtension.php.old

Only `*.php` file is loaded, not the `*.php.old` one. This way you can **be sure the new code** is working before you generate patches.

<br>
Make sure to back up other modified files in the vendor/ directory as well as some of the commands below may overwrite them.

### 3. Run `generate` command 🥳️

Expand All @@ -61,8 +55,6 @@ This tool will generate **patch files for all files created this** way in `/patc

The patch path is based on original file path, so **the patch name is always unique**.

<br>

Also, it will add configuration for `cweagans/composer-patches` to your `composer.json`:

```json
Expand All @@ -77,23 +69,31 @@ Also, it will add configuration for `cweagans/composer-patches` to your `compose
}
```

<br>
#### 3.1 When using cweagans/composer-patches v2

Optionally, if you use a [patches file](https://docs.cweagans.net/composer-patches/usage/defining-patches/#patches-file) you can specify its path using the `--patches-file` option:
`cweagans/composer-patches` v2 requires the execution of 2 additional steps after generating the patches:

Updating the `patches.lock.json` file:

```bash
vendor/bin/vendor-patches generate --patches-file=patches.json
composer patches-relock
```

You can choose to write the patches to a different folder than the default 'patches' folder by specifying the folder name using the `--patches-folder` option:
Applying the new patches:

```bash
vendor/bin/vendor-patches generate --patches-folder=patches-composer
composer patches-repatch
```

That's it!
### 4. Final steps

Now you need to do run composer to update the lock file as the checksum of `composer.json` has changed:

```bash
composer update --lock
```

<br>
That's it!

Now all you need to do is run composer:

Expand All @@ -103,15 +103,41 @@ composer install

And your patches are applied to your code!

<br>

If not, get more information from composer to find out why:

```bash
composer install --verbose
```

<br>
### Summary

To summarize, the generate workflow is:

```bash
# generate patches
vendor/bin/vendor-patches generate
# (if using cweagans/composer-patches v2)
Copy link
Member

@TomasVotruba TomasVotruba Jan 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm thinking, what is the added value of v2 here? It seems more and more work.

Instead, we should handle this for a user. Any chance we can include this complexity into our generate command to keep it working as before?

Copy link
Contributor Author

@M-arcus M-arcus Jan 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I updated the README instructions because without executing the 2 additional commands, nothing happens to files in vendor/. This might lead to people just installing and assuming that files in vendor/ are patched.

I can add another PR that checks if v2 is installed and triggers the relock and repatch commands after generating the patch.

composer patches-relock
composer patches-repatch
# update the lock file
composer update --lock
# install with patches applied
composer install
```

## Patches File and Patches Folder Options

Optionally, if you use a [patches file](https://docs.cweagans.net/composer-patches/usage/defining-patches/#patches-file) you can specify its path using the `--patches-file` option:

```bash
vendor/bin/vendor-patches generate --patches-file=patches.json
```

You can choose to write the patches to a different folder than the default 'patches' folder by specifying the folder name using the `--patches-folder` option:

```bash
vendor/bin/vendor-patches generate --patches-folder=patches-composer
```

## TroubleShooting

Expand All @@ -121,7 +147,7 @@ If you are upgrading `cweagans/composer-patches` to 2.0.0 and newer versions, yo

The new version requires that `--- /dev/null` needs to be replaced with `--- <file-path>` in your patch files.

For example, if you have a old patch file that starts with:
For example, if you have an old patch file that starts with:

```diff
--- /dev/null
Expand Down Expand Up @@ -153,5 +179,3 @@ and register to `.bash_profile` or `.zshrc` (if you're using [oh-my-zsh](https:/
```
PATH="/opt/homebrew/opt/gpatch/libexec/gnubin:$PATH"
```

<br>