PHPackages                             devkit/composer-link - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. devkit/composer-link

ActiveComposer-plugin[Utility & Helpers](/categories/utility)

devkit/composer-link
====================

Link local Composer packages via path repositories. Composer plugin: `composer link`, `composer add`, `link-help`, `local-bootstrap`, `local-install`, and related commands.

v1.0.0(1mo ago)329↑11.1%MITPHPPHP ^8.3CI passing

Since Apr 18Pushed 1mo agoCompare

[ Source](https://github.com/stuarttodd-dev/devkit-composer-link)[ Packagist](https://packagist.org/packages/devkit/composer-link)[ Fund](https://buymeacoffee.com/stuarttodd)[ RSS](/packages/devkit-composer-link/feed)WikiDiscussions main Synced 1w ago

READMEChangelog (1)Dependencies (11)Versions (2)Used By (0)

 [![Composer Link](./devkit-logo.png)](./devkit-logo.png)**Composer Link**
*Local package path overrides for Composer.*

devkit-composer-link
====================

[](#devkit-composer-link)

**Local path overrides for Composer dependencies**, with a separate local manifest so your committed `composer.json` and `composer.lock` stay clean.

Package: **`devkit/composer-link`**

Why this exists
---------------

[](#why-this-exists)

When you need to test package changes inside a real app, the usual workflow often requires:

- hand-edit root `composer.json` repositories
- point dependencies at local folders
- remember to undo everything before committing

Composer Link stores local override state in dedicated local files, rebuilds managed path repositories, and keeps your team baseline untouched.

Prerequisites
-------------

[](#prerequisites)

- PHP **8.3+**
- Composer **2.2+** (plugin allow-list support)

Install
-------

[](#install)

Install in the **consuming application** (not in the library repo you are editing):

```
composer require --dev devkit/composer-link
```

Allow the plugin (Composer 2.2+)
--------------------------------

[](#allow-the-plugin-composer-22)

Approve the interactive prompt, or add this explicitly:

```
{
  "config": {
    "allow-plugins": {
      "devkit/composer-link": true
    }
  }
}
```

Run from project root
---------------------

[](#run-from-project-root)

All commands should run from your **application root** (where the committed `composer.json` lives).

Use:

```
composer link-help
```

If the package is installed correctly, `composer list` will include: `link`, `add`, `unlink`, `promote`, `linked`, `refresh`, `link-doctor`, `local-bootstrap`, `local-install`, `link-help`.

At a glance
-----------

[](#at-a-glance)

CommandIn one sentence**`link`**Override an existing dependency to a local path.**`add`**Bootstrap a dependency from local path before it exists in committed manifest/registry.**`unlink`**Remove local override state and restore or remove requirement.**`promote`**Move a locally-managed package back to a published constraint.**`linked`**Show all packages currently managed by Composer Link.**`refresh`**Rebuild managed path repositories in local manifest from state file.**`link-doctor`**Verify local setup and ensure ignore rules/local files are correct.**`local-bootstrap`**Copy committed manifest/lock into local manifest/lock files.**`local-install`**Install using local manifest (`COMPOSER=composer.local.json`).**`link-help`**Print a concise command/arguments/options overview in terminal.Configuration
-------------

[](#configuration)

Composer Link reads optional config from root `composer.json` under `extra.composer-link`.

```
{
  "extra": {
    "composer-link": {
      "overrides_file": "packages-local.json",
      "local_composer_json": "composer.local.json"
    }
  }
}
```

KeyRole**`overrides_file`**Local state file with managed packages, paths, mode, constraints.**`local_composer_json`**Local Composer manifest used for path repositories and local update/install runs.Files and folders
-----------------

[](#files-and-folders)

Default local artifacts:

- **`packages-local.json`**: plugin state (gitignore this).
- **`composer.local.json`**: local manifest (gitignore this).
- **`composer.local.lock`**: lockfile for local manifest (gitignore this).

Committed baseline files stay canonical:

- **`composer.json`**
- **`composer.lock`**

Legacy note: `composer.local-packages.json` is read only as fallback when `packages-local.json` is missing/empty; next write persists to `packages-local.json`.

Command reference
-----------------

[](#command-reference)

Use `composer help ` for full option docs.

### `link` — override existing dependency

[](#link--override-existing-dependency)

```
composer link
```

Examples:

```
composer link my-vendor/my-package ../packages/my-package
composer link my-vendor/my-package ../packages/my-package --constraint=@dev
composer link my-vendor/my-package ../packages/my-package --no-update
composer link my-vendor/my-package ../packages/my-package --no-symlink
```

### `add` — bootstrap new local dependency

[](#add--bootstrap-new-local-dependency)

```
composer add
```

Examples:

```
composer add my-vendor/new-lib ./libs/new-lib
composer add my-vendor/new-lib ./libs/new-lib --no-dev
composer add my-vendor/new-lib ./libs/new-lib --constraint=^0.1
```

### `unlink` — stop managing a package locally

[](#unlink--stop-managing-a-package-locally)

```
composer unlink
```

If package was added via `add`, use `--remove` to remove requirement:

```
composer unlink my-vendor/experimental-package --remove
```

Useful flags:

- `--no-update`
- `--remove` (required for bootstrap-mode removals)

### `promote` — move to published constraint

[](#promote--move-to-published-constraint)

```
composer promote
```

Examples:

```
composer promote my-vendor/my-package ^1.5
composer promote my-vendor/my-package ~2.3.0
composer promote my-vendor/my-package ^1.0 --no-update
```

### `linked` — show managed packages

[](#linked--show-managed-packages)

```
composer linked
```

Outputs package, mode (`override`/`bootstrap`), path, symlink behavior, constraint, and path status.

### `refresh` — rebuild managed path repos

[](#refresh--rebuild-managed-path-repos)

```
composer refresh
composer refresh --no-update
```

### `link-doctor` — validate setup

[](#link-doctor--validate-setup)

```
composer link-doctor
```

Checks:

- local ignore block/files
- linked path existence
- count of plugin-managed path repositories in local manifest

### `local-bootstrap` — create local manifest files

[](#local-bootstrap--create-local-manifest-files)

```
composer local-bootstrap
composer local-bootstrap --force
```

Copies committed `composer.json` (+ `composer.lock` if present) to local equivalents.

### `local-install` — install via local manifest

[](#local-install--install-via-local-manifest)

```
composer local-install
```

Equivalent to:

```
COMPOSER=composer.local.json composer install
```

Examples:

```
composer local-install --no-dev
composer local-install --prefer-dist
composer local-install --no-scripts
```

### `link-help` — command summary in terminal

[](#link-help--command-summary-in-terminal)

```
composer link-help
composer help link-help
```

Typical workflows
-----------------

[](#typical-workflows)

### Override a released package with local checkout

[](#override-a-released-package-with-local-checkout)

```
composer link your-vendor/your-package ../packages/your-package
```

If local branch/version does not satisfy baseline constraint:

```
composer link your-vendor/your-package ../packages/your-package --constraint=@dev
```

### Bootstrap package before Packagist

[](#bootstrap-package-before-packagist)

```
composer add your-vendor/new-package ../packages/new-package
```

Later switch to published dependency:

```
composer promote your-vendor/new-package ^1.0
```

Version control and safety
--------------------------

[](#version-control-and-safety)

Keep shared baseline committed:

- `composer.json`
- `composer.lock`

Keep local override artifacts out of Git:

- `packages-local.json`
- `composer.local.json`
- `composer.local.lock`

`packages-local.json` is Composer Link state only; Composer itself reads whichever manifest `COMPOSER` points to.

For local workflows:

```
composer local-bootstrap
composer link vendor/package ../path/to/package
composer local-install
```

Before merging release work, align committed manifest/lock with intended published constraints (via `promote`, `unlink`, or normal manifest edits).

Support
-------

[](#support)

If this project saves you time and you want to support future updates:

- [Buy Me a Coffee](https://buymeacoffee.com/stuarttodd)

License
-------

[](#license)

MIT (see `composer.json`).

###  Health Score

42

—

FairBetter than 88% of packages

Maintenance90

Actively maintained with recent releases

Popularity14

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity48

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

52d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/54860041?v=4)[Stuart Todd](/maintainers/stuarttodd-dev)[@stuarttodd-dev](https://github.com/stuarttodd-dev)

---

Top Contributors

[![stuarttodd-dev](https://avatars.githubusercontent.com/u/54860041?v=4)](https://github.com/stuarttodd-dev "stuarttodd-dev (1 commits)")

###  Code Quality

TestsPest

Static AnalysisPHPStan, Rector

Code StylePHP\_CodeSniffer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/devkit-composer-link/health.svg)

```
[![Health](https://phpackages.com/badges/devkit-composer-link/health.svg)](https://phpackages.com/packages/devkit-composer-link)
```

###  Alternatives

[matomo/matomo

Matomo is the leading Free/Libre open analytics platform

21.6k38.2k](/packages/matomo-matomo)[composer/composer

Composer helps you declare, manage and install dependencies of PHP projects. It ensures you have the right stack everywhere.

29.4k193.1M3.0k](/packages/composer-composer)[friendsofphp/php-cs-fixer

A tool to automatically fix PHP code style

13.5k245.4M23.7k](/packages/friendsofphp-php-cs-fixer)[drupal/core

Drupal is an open source content management platform powering millions of websites and applications.

21764.8M1.6k](/packages/drupal-core)[drupal/core-recommended

Locked core dependencies; require this project INSTEAD OF drupal/core.

6941.5M395](/packages/drupal-core-recommended)[shopware/core

Shopware platform is the core for all Shopware ecommerce products.

585.4M506](/packages/shopware-core)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)