Composer: how to use local symlinks for packages in development but Git versions in production

Question

I have a project with a composer.json where some libraries are pulled from our GitLab:

"require": {
    "my/library": "1.0.0",
    "my/library-second": "1.2.1"
}

On production, this works fine — Composer fetches the packages from Git.

However, during development, I need to make changes to these libraries locally without creating a release. I want to use path repositories with symlink to my local folder.

The problems I face:

• If I add local path repositories directly to the main composer.json, it breaks the production build.

• Using replace or dev-master leads to conflicts with the fixed versions (1.0.0 / 1.2.1).

• Ideally, I want a way to have a separate local composer.json or override only on the dev machine, so that:

1. locally the packages are installed as symlinks,

2. on production the stable Git versions are used,

3. the main composer.json remains unchanged.

Question:

What is the proper way to structure Composer for this use case?

• Is there a standard practice or common pattern to separate local and production Composer configuration, while keeping symlinks for local packages during development?

• How do PHP projects usually handle local development with symlinks on packages without touching production composer.json?

Answer 1

You can have two composer.json like this:

// composer.json (the one used in production and pushed to github)
{
  "require": {
    "my/library": "1.0.0",
    "my/library-second": "1.2.1"
  },
}

Then

// composer.local.json (the one used in local development - You should add this to .gitignore) - Use symlink to the package

{
  "repositories": [
    {
      "type": "path",
      "url": "../my-library",
      "options": {
        "symlink": true
      }
    },
    {
      "type": "path",
      "url": "../my-library-second",
      "options": {
        "symlink": true
      }
    }
  ],
  "require": {
    "my/library": "*",
    "my/library-second": "*"
  },
  "minimum-stability": "dev"
}

You may want to set "minimum-stability": "dev".

Then when running composer commands in your local env, you can specify the composer.local.json

COMPOSER=composer.local.json composer install

You can even create an alias in your .bashrc file (if you using linux - I don't know about aliases in other OS)

alias composer-local='COMPOSER=composer.local.json composer'

Then you can use as

composer-local install

Answer 2

Messing about and faking local dependencies is never going to be maintainable, nor is locally modifying dependant libraries.

1. Make a new branch in each library repo for relevant modifications, eg: feature-X.
2. Modify the main app's composer.json to have the library's require statement reference the branch, eg: "require": { "my-lib": "@feature-X" }
3. Commit to relevant feature branches as necessary.
4. Solidify new release versions to libraries.
5. Push new version of the app with updated library version requirements.

Ref: https://getcomposer.org/doc/04-schema.md#package-links