README

Switch a project between its live Composer dependencies and local clones of those packages, using plain Composer scripts.

Develop your packages side by side

When you work on a library and the project that uses it at the same time, you want edits in the library to show up in the project right away, without tagging a release or pushing a branch. Composer Local Switcher makes that a one-command switch: it swaps the packages you name for symlinked path repositories pointing at your local clones, and restores your production composer.json and lock file when you switch back.

Features

Switch between a production and a local development configuration with a single command, composer switch-dev or composer switch-prod - it shows you the changes, confirms, and runs Composer itself.
Work on local package clones through symlinked path repositories, so changes in a library are visible in the project that uses it.
Keep a separate lock file for each configuration, so you can run Composer commands in either mode.
Preview any switch before it happens; the preview lists the planned file changes and writes nothing.
Inspect the current mode and the state of every managed file, as a readable report or as JSON.
Carry edits made while in development mode - including composer require/remove - back into production instead of overwriting them.
Block a switch before any file is written when a local package's pinned version override cannot satisfy the project's own dependency constraint, instead of letting composer update fail partway through.
Spot the active mode at a glance in your file browser through DEV/PROD flag files.
Block commits of the development configuration with a bundled git pre-commit hook.
Drive the switcher from PHP code or tooling: results and errors come back as structured objects, so you never need to parse console output.
Add it to a project with no runtime dependencies beyond PHP.

Requirements

PHP 8.4 or newer
Composer

Quick Start

Run these commands in the root of a project that has a composer.json. The steps install the library, wire up three scripts, set up the configuration files, and preview a switch to development mode without changing anything.

composer require mistralys/composer-local-switcher

composer config scripts.switch-dev "Mistralys\\ComposerSwitcher\\ConfigSwitcher::composerSwitchDev"
composer config scripts.switch-prod "Mistralys\\ComposerSwitcher\\ConfigSwitcher::composerSwitchProd"
composer config scripts.switch-preview-dev "Mistralys\\ComposerSwitcher\\ConfigSwitcher::composerSwitchPreviewDev"

mkdir -p composer
echo '{"local-repositories": []}' > composer/local-repositories.json

composer switch-preview-dev

The preview prints a header naming it as a preview and the transition it's previewing (a first-ever switch always starts from the production-equivalent initial state, so it reads PROD → DEV), followed by any composer.json changes it would make - with nothing yet to change for an empty local-repositories.json, that header is the whole output:

Composer Local Switcher — preview of switch PROD → DEV (nothing will be changed)

Run with -v to also see each planned file operation (would <type>: <source> -> <target> (<reason>)) and the switcher's internal bookkeeping messages, both hidden at default verbosity.

From here:

List the packages you want to work on locally in composer/local-repositories.json, with the path to each clone. The Setup Guide shows the format.
Run composer switch-dev. It prints the composer.json changes it's about to make and the Composer command it's about to run, asks you to confirm, then runs that command itself - one command, nothing left to run by hand.
When you are done, run composer switch-prod the same way.

A real switch shows you what it's about to do before it does it, then frames the Composer run it executes for you. The first block is the plan, naming the transition it's making:

Composer Local Switcher — switch PROD → DEV
composer.json changes (1):
  local path `../package-name` for `vendor/package-name` (symlinked, as version `1.4.2` from `options.versions`)
Next: composer update vendor/package-name (Installing the switched local packages at their aliased versions.)
Apply these changes and run `composer update vendor/package-name`? [yes]
Composer Local Switcher — running `composer update vendor/package-name`
  Installing the switched local packages at their aliased versions.
...Composer's own output...
Composer Local Switcher — switch to DEV done

Add -v (composer -v switch-dev) to also see each file operation and the switcher's bookkeeping messages, which carry their numeric [code] prefix. Both are hidden by default.

If a package's pinned version in local-repositories.json cannot satisfy its constraint in your composer.json (for example a leftover 1.0.4 pin against ^3.0.0), the switch stops before it writes anything, names the package, the pinned version, the constraint and the PROD-locked version, and exits non-zero:

Composer Local Switcher — switch PROD → DEV blocked, nothing was changed
  ! WARNING: The version override [1.0.4] for [vendor/package-name] does not satisfy its root require constraint [^3.0.0] (PROD-locked version: 3.0.0). Fix: edit the override in `local-repositories.json`, or adjust the root constraint, so the override satisfies it.
ERROR: The switch is blocked by a precondition (see the messages above).

If the Composer command a switch runs fails, the switcher prints how to recover (fix the cause and run composer switch-update, or run composer switch-prod to fall back) and exits non-zero. The switch is not rolled back automatically. See the Usage Guide for details.

Running non-interactively (scripts, CI, agents)? Add -- --yes to apply without being asked: composer switch-dev -- --yes. See Usage Guide for the full behavior.

Learn More

Resource	Description
Setup Guide	How it works, the configuration files, script wiring, custom file layouts, pinned package versions, and what to commit.
Usage Guide	Switching, previewing, and inspecting state from the command line.
API Guide	Using the switcher from PHP: outcomes, options, and exception handling.
Git Hooks	Installing the pre-commit hook that guards against committing the development configuration.
Migrating from 2.x	Consumer migration steps to the single-source-of-truth model: untracking `composer-prod.*`, the optional `version` override, and removed APIs.
Migrating from 1.x	The PHP 8.4 requirement and the PHP API changes that affect code calling the library directly.
Changelog	Release history.
Issues	Report a bug or request a feature.

License

MIT. See LICENSE.

mistralys / composer-local-switcher

Package info

Security

Statistics