Recent Posts


Composer Path Repositories


Frustrated by Magento? Then you’ll love Commerce Bug, the must have debugging extension for anyone using Magento. Whether you’re just starting out or you’re a seasoned pro, Commerce Bug will save you and your team hours everyday. Grab a copy and start working with Magento instead of against it.

Updated for Magento 2! No Frills Magento Layout is the only Magento front end book you'll ever need. Get your copy today!

By default, when you run

$ composer require some/package

Composer will ask where it can find the some/package package, (this is usually, but not always, a GitHub repo) Once composer knows where to find a package, it will download the package into your ./vendor folder. is a composer repository. However, it is not the only composer repository. Composer has a number of different repository types that allow you to tell composer to look for packages from other sources.

For example, if you’re a Magento 2 developer you’re probably familiar with — this authenticated repository is how Magento distributes its composer packages. When you create a new Magento 2 project, you add this repository to your configuration file via the --repository-url option

% composer create-project --repository-url= \
    magento/project-community-edition \

Composer also allows you to create “a repository of one package”. The most common example of this is the vcs repository type. A vcs repository allows you to tell composer “look at this git, mercurial, or svn repository for a package” by adding the following to your configuration.

    "repositories": [
            "type": "vcs",
            "url": ""

This tells composer the GitHub repository at contains a composer package. Composer will check this repository’s composer.json file when it’s looking for packages. In this particular case, a request to use monolog/monolog

% composer require monolog/monolog

would pull this package from instead of the source provided by

It may feel slightly overblown to call this a “repository” since it only contains a single package, but it works all the same.

Today we’re going to take a look at another “single package” repository type — the path repository.

The Path Repository

Path repositories allow you to point at a directory on your computer and treat it as a composer repository. In addition to this, when composer installs a package from a path repository is does not copy the files. Instead, it creates a symlink in your vendor folder to the path. This makes it ideal for working on a package that’s part of a larger system.

Let’s look at an example. The GitHub repository contain a composer package. Let’s clone this to our local system.

% git clone

This package’s name is astorm/hello-path-repository.

In a separate folder, let’s create a composer.json file that tells composer the hello-path-repository folder is a a path repository.

% ls

% mkdir our-project
% cd our-project
% touch composer.json

With an empty composer.json created, let’s add the path repository configuration.

// File: composer.json
    "repositories": [
            "type": "path",
            "url": "../hello-path-repository"

Now, with the above composer file in place, let’s require the astorm/hello-path-repository package.

% composer require astorm/hello-path-repository

Using version ^1.0 for astorm/hello-path-repository
./composer.json has been updated
Running composer update astorm/hello-path-repository
Loading composer repositories with package information
Updating dependencies
Lock file operations: 1 install, 0 updates, 0 removals
  - Locking astorm/hello-path-repository (1.0)
Writing lock file
Installing dependencies from lock file (including require-dev)
Package operations: 1 install, 0 updates, 0 removals
  - Installing astorm/hello-path-repository (1.0): Symlinking from ../hello-path-repository
Generating autoload files

If we look at our vendor folder,

% ls -l vendor/astorm
total 0
lrwxr-xr-x  1 astorm  staff  30 May 17 09:58 \
    hello-path-repository -> ../../../hello-path-repository

we’ll see that astorm/hello-path-repository is now a symlink to our cloned repository.

% php vendor/astorm/hello-path-repository/hello.php
Hello World

That’s path repositories. They let you point at a local folder on your computer and treat that folder as a single package composer repository.

Path Repositories and composer.lock

If you’re going to use path repositories (or you’re going to use a project that uses them), you’ll need to be careful/aware of your composer.lock file. Once you’ve generated a composer.lock file, that file becomes the source of truth for where composer will download a package. If we look at the composer.lock file generated by the above activity

/* ... */
"packages": [
        "name": "astorm/hello-path-repository",
        "version": "1.0",
        "dist": {
            "type": "path",
            "url": "../hello-path-repository",
            "reference": "2ecb421aee5132f7bdbb25d7d15f3c4d0bf81572"
        /* ... */
/* ... */

we see it’s pointing to our ../hello-path-repository path.

In our case, this isn’t a big deal since astorm/hello-path-repository doesn’t exist at However, if it did and we’d installed with an invalid path repository, composer will fall back to installing the package from and then put that location in you lock file.

If you want a second chance at installing from your path repository, you’ll need to remove your composer.lock file. This can also complicate development if you want to use a path repository with a project that distributes a composer.lock file.

These gotchas can make path repositories a less universal tool than they might otherwise be, but they’re still a useful tool to have in your composer belt.

Series NavigationShopware’s psh.phar Command Line Tool >>

Copyright © Alana Storm 1975 – 2023 All Rights Reserved

Originally Posted: 18th May 2021

email hidden; JavaScript is required