Testing Laravel framework contributions in a local Laravel install

Jun 23, 2017

Imagine this scenario: You want to contribute to the Laravel framework, whether it be an idea for a new Collection method, a string helper, or even just a small spelling fix. Naturally, you fork Laravel, pull down a local copy, and make the change you wish to submit in a pull request. But before you are ready to submit your PR, you want to test it locally in a real-life Laravel app; so, you create a fresh app using laravel new [your-app-name], but now what?

Ultimately, you need some way to replace the Laravel framework from your app’s vendor directory with your local fork of Laravel that includes your new code. There are multiple ways to do this, but here is the most streamlined and simple method. This is the workflow Taylor Otwell uses and talked about at Laracon Online, and which was also covered in another blog post here.

Step 1: Fork the framework locally

Visit the Laravel framework repository and fork it: GitHub - laravel/framework.

Now, clone the forked repository in a directory on your local machine. I tend to clone repos into a folder called sites served by Laravel Valet.

> git clone [the URL of your fork] ./laravel-framework

Make your code changes to this fork of laravel/framework.

Step 2: Create a new Laravel application

Create a new Laravel application that will be used to test out the changes you just made to laravel/framework.

> laravel new laravel-framework-app

Step 3: Setup composer.json

In the new laravel-framework-app directory (cd laravel-framework-app), modify the composer.json file to include the following:

First, add a "repositories" key, which is not there by default:

"repositories": [
    {
        "type": "path",
        "url": "../laravel-framework"
    }
],

This next step is important: The version specified here must match the checked-out branch of the locally forked framework.

If the currently checked-out branch is main, then the version in the composer.json file should be dev-main. However if the current branch is 5.4, setting the composer version to dev-5.4 will not work because of the .. When this is the case, the convention is: version.x-dev so 5.4.x-dev will do the trick.

"require": {
    ...
    "laravel/framework": "5.4.x-dev",
    ...
},

Here is a gist of my composer.json file if you don’t want to manually make the modifications: modified-composer.json · GitHub

Step 4: Update via composer

Now it’s time to run composer update on laravel/framework, to force Composer to use our local fork instead of the public repository downloaded from Packagist.

Composer will hopefully notice the added repository, and symlink to your local fork. If you do not see the following message: Symlinked from ../laravel-framework, then you probably specified the wrong local branch in the composer.json file in step #3.

> composer update laravel/framework

Wrapping up

You should now have a running Laravel app that uses your locally-forked version of the framework. This will allow you to test out your framework contributions in an application context, without the need for painstaking manual work.

Enjoy!