mistralys / composer-local-switcher

3.0.0 2026-10-08 07:51 UTC

Requires

• php: >=8.4

Requires (Dev)

• phpstan/phpstan: >=1.10
• phpstan/phpstan-phpunit: >=1.3
• phpunit/phpunit: >=13.0
• roave/security-advisories: dev-latest
• symfony/process: ^7.0 || ^8.0

MIT

• Sebastian Mordziol

Published on Packagist.org on 2026-10-08 07:53 UTC

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.
• 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 each file operation it would perform as would <type>: <source> -> <target> (<reason>), followed by the messages a real switch would show:

Dry run: no files will actually be changed.
Using Composer DEV configuration.
Run `composer update` to create a DEV lock file.
Rebuilt a fresh DEV `composer.json`.

From here:

1. 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.
2. 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.
3. 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:

composer.json changes:
  require › vendor/package-name: changed "^2.0" -> "*" [version]
Planned command: composer update vendor/package-name (local repository added)
Apply these changes and run `composer update vendor/package-name`? [yes]

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.