How to patch a Composer dependency without forking it?

When you’re working on a PHP project that uses Composer for dependency management, one of your libraries may have a bug or require a specific change to meet your needs. The quick solution that often comes to mind is to fork the repository, make the necessary changes, and then use it as the source in your project.

However, this approach isn’t always ideal. Forking a dependency means taking on its maintenance, keeping up with its updates, and handling potential future incompatibilities. That can quickly become a burden, especially if you have to maintain multiple forks.

Fortunately, there’s an elegant alternative: apply a patch directly to the dependency, without needing to fork. This method lets you fix or modify the library’s behavior while still benefiting from official updates.

In this article, we’ll explore how to use Composer and related tools to apply patches to your dependencies effectively, in a maintainable way, and without complicating your workflow. Whether you’re a beginner or an experienced developer, this technique can save you time and simplify managing your projects.

4 steps to create your patch

1 - Install the packages needed for patching

composer require cweagans/composer-patches symplify/vendor-patches --dev

2 - Prepare the patch file

In your vendor directory, once you’ve identified the right file, create a copy of it by appending “.old”.

cp vendor/package/toto/src/toto.php vendor/package/toto/src/toto.php.old

Now just edit the “.php” file and apply your changes.

Only *.php files are loaded, not *.php.old files. This way, you can make sure the new code works properly before generating the patches.

3 - Create the patch

Run the following command:

vendor/bin/vendor-patches generate

This will generate a file in the patches folder; here’s an example:

/patches/package-toto-src-toto.php.patch

The patch path is created from the path of the original file, which ensures the patch name is always unique.

In addition, the configuration for cweagans/composer-patches is added to your composer.json file:

{
    "extra": {
        "enable-patching": true,
        "patches": {
            "package/toto": [
                "patches/package-toto-src-toto.php.patch"
            ]
        }
    }
}

4 - Reinstall the packages and verify the patch

Simply check that everything works by cleaning things up.

The simplest way is to delete the vendor folder and reinstall the packages:

rm -Rf vendor
composer install

And there you have it—you’re now a master at patching your dependencies without breaking everything (well, almost)! With this method, you’ll fix bugs faster than your coworker fixes typos in Slack. So, get typing, and may your projects be as stable as a server at 6 p.m. on a Friday! ?