How to set up your local projects to contribute to Laravel (or any PHP library) : a practical guide

Let’s imagine this scenario: You are working on a Laravel application, and you found a bug either in the framework itself or in one of the third party libraries you are using. You edit the code inside your project, or maybe you installed a fresh copy of Laravel and library that has the issue, and you edited the code there. You saved the changes, but when you went to your terminal to commit the changes, GIT just ignored what you did. You start wondering “What’s happening here?”.

The first solution that might pop up in your head could be to read the “How to contribute” of the framework or the library documentation, and in most cases, you’d find there the necessary steps to contribute to the framework, but I always felt that something was missing in the documentation. Let me explain what I mean by that:

Let’s take the example of Laravel here, if you decide to contribute to the framework, you’d need to clone the laravel/framework repository, push your changes to your own copy of the repository (on github), and create a PR, but what’s missing here is How would you test your changes (bug fix, new feature, …) in a local project, since if you introduce the changes in that project you just can’t commit them and create a PR for them easily, and if you change the code in the laravel/framework repository you just cloned you might end up doing a lot of copy/pasting between this repository and your project in order to test those changes.

Luckily there is a cleaner way to deal with all this. I’m not going to walk you through the usual steps of creating a PR, I assume since you are reading this article you are already familiar with that. I’ll focus on how you should set up your local environment to streamline this whole process and show you how you could fix bugs and develop new features in the framework/library and test them locally before you create the PR you are about to send.

Prepare your test project and your repository

First, you’d need to fork the

laravel/framework

➜ laravel pwd
/home/djug/laravel
➜ laravel ls
framework playground

Make Composer load the changes from the local repository

Now, with the most important part. We need to tell the

playground

/home/djug/laravel/framework

We can do this via composer, and according to its documentation and I’m quoting here:

Loading a package from a VCS repositoryThere are a few use cases for this. The most common one is maintaining your own fork of a third party library. If you are using a certain library for your project and you decide to change something in the library, you will want your project to use the patched version. If the library is on GitHub (this is the case most of the time), you can simply fork it there and push your changes to your fork. After that, you update the project’s composer.json. All you have to do is add your fork as a repository and update the version constraint to point to your custom branch.

So the first part of the

composer.json

playground

{
    "name": "laravel/laravel",
    "type": "project",
    "description": "The Laravel Framework.",
    "keywords": [
    "framework",
    "laravel"
    ],
    "license": "MIT",
    "repositories": [
        {
            "type": "vcs",
            "url": "/home/djug/laravel/framework/"
        }
    ],
    "require": {
        "php": "^7.1.3",
        "fideloper/proxy": "^4.0",
        "laravel/framework": "master",
        "laravel/tinker": "^1.0"
    },
...
}

Now each time I change something in the

/home/djug/laravel/framework/ 

composer update

playground

Push the changes to your remote repository and create a PR

Now that your playground repository can pull the changes from your framework repository, you could update add all the changes you want to your code and then test them on a “real” project.

After you finish testing, all that you need to do is to push the changes to your remote repository (your own “copy” of the

framework

Photo by John Schnobrich on Unsplash