Video Notes

In this guide I’ll cover how to use a forked version of a Composer package on Github. This can come in handy as a temporary solution if you identify a bug or issue in a package you’re using and the package maintainer is slow to address the issue.

For this demo, I’ll work with a freshly installed Laravel application, but this would work with any Composer managed PHP project. Within the application, I’ll target the dependency guzzlehttp/guzzle as an example since it comes installed by default with Laravel applications.

Make the fork

To get started, first create a fork of the package you’re working with by visiting the package homepage on Github and clicking the Fork button on the top right.

Next, edit the forked repository to address whatever change is needed and commit those changes.

Use the fork

To get your application to use the forked version of the package, edit its Composer config file (composer.json) adding a repositories section with the following settings, replacing the value for url with the Github URL to your forked package:

"repositories": [
    {
        "type": "vcs",
        "url": "https://github.com/susanBuck/guzzle"
        }
    ],
],

Finally, update your require section, setting the version constraint of the package in question to be dev-branch where branch is whatever branch name you made your edits on in your forked repository.

In my example, I worked on the branch master so I’ll set the guzzlehttp/guzzle package to version dev-master:

"require": {
    "guzzlehttp/guzzle": "dev-master",
    [...]
},

The key thing to note here is your require section is still referencing the original package guzzlehttp/guzzle, but the addition of the repositories config and the update to the version constraint makes it so that it’s imported from your fork, not the original source.

Test it

To test things worked as expected, run composer update to update your dependencies and then find the underlying source code for the package in your Composer vendor directory. Examining the code files you should be able to see the changes you made within your forked repository.

Misc

• Keep an eye out for future updates from the package you’re working with. If they release an update that addresses the issue, it’s best to revert your project back to the original repository so you can stay up to date with any future fixes and improvements.
• When it's time to revert your project back to the package’s original repository, simply remove the repository section from your Composer config and set an appropriate version constraint for the package.
• Read more about Composer’s VCS repository options here...