Using Composer Path Repositories for Local Development and Monorepo Workflows

Why Path Repositories Matter

When working on several inter‑dependent PHP packages inside a single codebase, publishing each change to Packagist is wasteful and slows feedback loops. Composer’s path repository type gives a clean way to replace a remote dependency with a local copy, making local development fast and reliable.

How Composer Handles a Path Repository

A path repository points Composer to a directory on your filesystem. When you run composer update, Composer will either create a symlink or copy the package into vendor/ (default is symlink on Unix, copy on Windows unless --prefer-symlink is used). The package is treated exactly like any other dependency: autoload files are merged, version constraints are respected, and the package name stays the same.

Example composer.json snippet:

{
    "require": {
        "my/package": "^1.0"
    },
    "repositories": [
        {
            "type": "path",
            "url": "../my-local-package",
            "options": { "symlink": true }
        }
    ]
}

In this example my/package is replaced by the local folder ../my-local-package. The options.symlink flag forces a symlink; omit it to let Composer copy the files.

Monorepo‑Friendly Structure

Place all packages under a single repository root. Each package’s composer.json can reference its siblings via relative paths:

{
    "name": "vendor/package-a",
    "require": {
        "vendor/package-b": "*"
    },
    "repositories": [
        {
            "type": "path",
            "url": "../package-b",
            "options": { "symlink": true }
        }
    ]
}

Running composer install at the root pulls both packages into vendor/ as symlinks, keeping the autoloader coherent and eliminating the need to publish intermediate versions.

Trade‑offs and Limitations

• Not for Production – A path repository relies on a local directory that may not exist on the target server. Use a VCS or Packagist entry for production deployments.
• Relative Paths Can Break – In CI pipelines or when the repository is moved, relative paths may become invalid. Use absolute paths or environment variables if portability is a concern.
• Version Checks Bypassed – Composer treats the local package as if it already satisfies the version constraint, so a conflicting version may surface only at runtime. Verify the local composer.json version matches the constraint before committing.
• Symlink Permissions – Some hosting environments restrict symlink creation. In such cases, set options.symlink to false and let Composer copy the files.

Practical Verification Steps

1. Define the path repository in composer.json as shown above.
2. Run composer update (or install if the lock file already exists).
3. Use composer show vendor/package-a to confirm the source field points to the local path and the version matches the package’s composer.json.
4. Inspect vendor/vendor/package-a – it should be a symlink (or a copy) of the source directory.
5. Remove the path entry and run composer update again to ensure Composer falls back to the remote Packagist package.

Actionable Takeaway

Use path repositories to keep your monorepo development fast and your dependencies isolated. Keep the path entries out of your production lock file, guard relative paths with environment variables, and double‑check version compatibility before merging. This approach lets you iterate on multiple packages simultaneously without the overhead of publishing each change.