Require a local Composer package for development

Introduction

In PHP world Composer is currently the industry standard handling third-party packages. It allows us to automatically download the code libraries from Packagist along with all of their dependencies.

When developing a package that is going to be used in a framework, say Laravel for example, you don’t want to constantly push changes and require the package in a “real” project to test the integration. Wouldn’t be nice to include the local version of the package and test it straight away, as if it was just pulled from Packagist? You can then publish the changes and tag new releases only when you feel comfortable enough, speeding up the whole development process.

Luckily Composer provides this functionality out of the box, using some symlink magic under the hood.

Create the Package

In the composer.json file of your package you need to specify the package name and the PSR-4 autoload definition that maps the namespace to the src folder (or wherever the source code of your package lives).

{
    "name": "acme/my-package",
    "description": "My package for Laravel framework",
    "autoload": {
        "psr-4": {
            "Acme\\Package\\": "src"
        }
    },
}

Configure the application

Now inside the application that uses the package you need to add a new repository definition. Check out the "repositories" key, and if you don’t have one go ahead and create it now:

{
    "name": "acme/my-package",

    ...

    "repositories": [
        {
            "type": "path",
            "url": "/home/vagrant/code/my-package",
            "options": {
                "symlink": true
            }
        }
    ]
}

The above snippet tells Composer to include a new “repository” which contains your package and symlink it to your working code folder. By writing "type": "path" Composer knows that you would like to reference a local repository and the url defines its location (the path can be relative or absolute).

You can do the same with multiple packages, by nesting them inside the path declared above (e.g. /home/vagrant/code/my-packages/package1 and /home/vagrant/code/my-packages/package2 under the same folder "url": "/home/vagrant/code/my-packages").

Require the package

The next step is to tell Composer that we want to pull in our package that is currently in development, so we’ll need to specify that as a requirement:

"require": {
    "acme/my-package": "@dev"
}

With this snippet the package will be pulled in as a dev package on the master branch (dev-master). If you want to pull another branch you can change it by using dev-[branchname] instead.

Now all that’s left is to run the command composer update acme/my-package --prefer-source. This will tell Composer to bring in your new local package and prefer the source (local repository) version instead of a distribution build.

If it does not work make sure to have these values in the composer.json file

{
    "minimum-stability": "dev",
    "prefer-stable": false,
}

You will now have a symlink’d Composer package local to your project which can be edited directly from your /vendor directory, allowing you to make changes and immediately test the results in your main project.