Composer symlinker with Dotenv support

A Composer plugin to install packages as local symbolic links.

This plugin is a temporary implementation of using symbolic links to local packages as dependencies to allow a parallel work process. For a descriptive (and commented) problematic, see composer/composer#1299.

In this Fork you can find additional support for vlucas/phpdotenv which is used by various frameworks out there. I use this feature in combination of an existing .env file which can be developer specific and is composer config independent.

Usage

To use it, just add it as a dependency in your composer.json:

"timhoepfner/composer-symlinker": "dev-master"

You must define concerned local paths or packages as extra config entries **or you can use your projects .env, see here **:

• local-dirs: a list of local paths to scan while searching a local version of a package ; the final package path will be completed with vendor/package ;
• local-packages: an array of vendor/package => local_path items ;
• local-vendors: a list of vendors to restrict local scanning.

"extra": {
    "local-dirs": [
        "/my/absolute/local/path1",
        "/my/absolute/local/path2"
    ],
    "local-vendors": [
        "vendor1",
        "vendor2"
    ],
    "local-packages": {
        "vendor/package1": "/my/absolute/path/to/vendor/package1",
        "vendor/package2": "/my/absolute/path/to/vendor/package2"
    }
}

Dotenv

The same configuration with .env will look like this, also with the nested variables feature offered by phpdotenv

Note If there is an existing configuration in your composer.json this will always be used instead of the settings within your .env due to compatibility.

LOCAL_DIR=/my/absolute/local
VENDOR_DIR=/my/absolute/path/to/vendor
COMPOSER_LOCAL_DIRS={$LOCAL_DIR}/path1,{$LOCAL_DIR}/path2
COMPOSER_LOCAL_VENDORS=vendor1,vendor2
COMPOSER_LOCAL_PACKAGES=vendor/package1:{$VENDOR_DIR}/package1,vendor/package2:{$VENDOR_DIR}/package2

Explanation

To separate multiple entries in one line you could use comma (,) or pipe (|) as delimiters

• Single entry e.g. COMPOSER_LOCAL_DIRS=/my/absolute/local
• Multiple entries e.g. COMPOSER_LOCAL_DIRS=/my/absolute/local,/another/local or COMPOSER_LOCAL_DIRS=/my/absolute/local|/another/local

To create a key:value list just use a colon (:)

• Single entry e.g. COMPOSER_LOCAL_PACKAGES=vendor/package1:/full/path/package1
• Multiple entries (see delimiters above) COMPOSER_LOCAL_PACKAGES=vendor/package1:/full/path/package1,vendor/package2:/full/path/package2 or COMPOSER_LOCAL_PACKAGES=vendor/package1:/full/path/package1|vendor/package2:/full/path/package2

Also it is possible to temporary disable this .env configuration, just add the following key

COMPOSER_LOCAL_DISABLED=1

Windows users warning

The plugin uses the internal symlink() PHP function. See Windows restrictions on the manual.

Quick tutorial

Let's say we want to work on a project named MyProject base on three dependencies: MyPackage1 and MyPackage2 which are some of our packages, and a third-party ExternalPackage which is not. Let's say our localhost architecture is the following:

[DOCUMENT_ROOT]
|
|projects/
|-------- MyVendor/
|----------------- MyPackage1/      // this is a clone of MyVendor/MyPackage1
|
|MyPackage2/                        // this is a clone of MyVendor/MyPackage2
|
|MyProject/                         // this is the project we currently work on
                                    // which depends on other three packages

Note: MyVendor/MyPackage1 and MyVendor\MyPackage2 must exist in some composer repository already before they can be considered by composer to be installed or symlinked. Typically, packages will already be accessible via Packagist. But if they are local only (no already configured repository) then a local one will need to be added to your composer.json. It might look like this:

  "repositories": [
    {
      "type":"vcs",
      "url":"/path/to/DOCUMENT_ROOT/projects/MyVendor/MyPackage1"
    }
  ]

As we want to work on both MyProject and its dependencies MyPackageX, we would usually first install our dependencies with Composer (as hard copies), to let it create a valid autoload.php, then we would manually replace these hard copies by local symbolic links to our clones of MyPackage1 and MyPackage2 ...

Well, the plugin can do this for us, as long as we well-configure it and forces Composer to use it when installing our dependencies.

The common way to force Composer to use the plugin when installing a dependency should be to include it in its require statement. In our case, this is not relevant as we only want to use it to build our local environment (it must not be a requirement for other users). A good way to do so is to create a "development-only" composer's configuration file for our project to let us install local dependencies with the plugin in our environment but let final users have a "real-life" behavior (the default one).

Our "development-only" composer.json could be:

"require": {
    "piwi/composer-symlinker": "1.*"
},
"require-dev": {
    "MyVendor/MyPackage1": "dev-master",
    "MyVendor/MyPackage2": "dev-master",
    "OtherVendor/ExternalPackage": "dev-master"
},
"extra": {
    "local-dirs": "/path/to/DOCUMENT_ROOT/projects/",
    "local-packages": {
        "MyVendor/MyPackage2": "/path/to/DOCUMENT_ROOT/MyPackage2"
    }
}

This way, we may first run:

$ composer install --no-dev

to install the plugin, then:

$ composer update

will use it to install all packages.

Our final vendor directory should be something like:

[vendor]
|
|MyVendor/
|--------- MyPackage1   => /path/to/DOCUMENT_ROOT/projects/MyVendor/MyPackage1 (symlink)
|--------- MyPackage2   => /path/to/DOCUMENT_ROOT/MyPackage2 (symlink)
|
|OtherVendor/
|----------- ExternalPackage/ (hard copy)

and our autoloader will be still valid.