Mark Jaquith

Sometimes when using Composer to manage PHP dependencies, you’ll encounter a situation where an upgrade to one of your packages or the installation of a new package is blocked because of two packages requiring non-overlapping versions of another package. The newer version of the dependency might just work fine with both packages, but one of them hasn’t updated their composer.json file to indicate that it works.

You might also hit a critical bug in a package that you can fix, or someone else has fixed, but the package hasn’t yet merged it and released a new version.

Don’t worry — this is not as much work as it sounds like.

Let’s consider a scenario where you need to fork and modify a package called vendor/packagename version 1.2.2 in Packagist.

1. Fork the Git Repository

First, fork the Git repository of the project.

2. Make Your Changes in a New Branch

Make a new Git branch, with a name that makes sense, and apply your changes to that branch. For this example, my new branch will be hotfix.

3. Add a Repositories Entry in Your Composer File

In your project’s composer.json, add a repositories key, or update an existing one, like so:

"repositories": [
    {
        "type": "vcs",
        "url": "https://github.com/markjaquith/packagename.git"
    }
],

4. Require Custom Version in Composer

Run composer require, specifying the name of the package plus a special version equal to dev- followed by your branch name.

composer require vendor/packagename:dev-hotfix

That’s it! The hotfix branch of your fork of the package will be installed from your Git repo.

5. Switch Back to Packagist Version

At some point in the future, when the vendor updates their package with the fix you needed, you can remove the repositories entry for your Git repo, and run composer require specifying a normal version constraint (making sure it requires the new version they released).

composer require "vendor/packagename:^1.2.3"