README

Composer Plug and Play lets you develop local packages inside a project without modifying composer.json. Keep your working packages in packages/, run composer plug-and-play, and get a fully resolved Composer environment — without polluting your real lock file.

Table of Contents

• Why?
• Requirements
• Installation
• Quick Start
• Directories and Files
• Commands
• Configuration
• Contributing
• License

Why?

Working with local packages via path repositories in composer.json pollutes the project's composer.json and composer.lock with development-only entries that must not be committed.

Composer Plug and Play keeps this configuration isolated in packages/composer.json and packages/plug-and-play.lock, so your real composer.json stays clean.

Requirements

• PHP 8.3 or higher
• Composer 2.3.0 or higher

Installation

composer require dex/composer-plug-and-play

Global installation

You can install Composer Plug and Play globally to use its abilities in all your local projects.

composer global require dex/composer-plug-and-play

Quick Start

1. Initialize the plug-and-play structure in your project:

   composer plug-and-play:init

2. Clone or create a package inside packages/:

   git clone git@github.com:your-org/your-package.git packages/your-org/your-package

3. Run plug-and-play to resolve everything:

   composer plug-and-play

Your package is now available as if installed via Composer, without touching composer.json.

Directories and Files

Composer Plug and Play plugin needs a packages folder in the project root directory where the plug and play structure will live.

packages/                           ← managed by plug-and-play
├── <vendor>/<package>/             ← your local package (cloned or created)
│   ├── composer.json
│   └── ...
├── composer.json                   ← your plug-and-play configuration
├── plug-and-play.json              ← generated merged config (do not commit)
└── plug-and-play.lock              ← generated lock file (do not commit)

composer.json                       ← your real project config (unchanged)
composer.lock                       ← your real lock file (unchanged)
vendor/                             ← standard Composer vendor directory

Commands

All commands use the plug-and-play.json and plug-and-play.lock files as source to project dependencies instead of composer.json and composer.lock original files.

You can use composer pp and composer pp:* as alias for all commands.

Configuration

You can add additional configuration in packages/composer.json under the extra.composer-plug-and-play key.

Ignore plugged packages

Sometimes you may need to ignore a package that is under development:

{
    "extra": {
        "composer-plug-and-play": {
            "ignore": [
                "vendor-name/package-to-ignore"
            ]
        }
    }
}

Require dev dependencies from plugged packages

When developing a package or library you may need to require its dev dependencies:

{
    "extra": {
        "composer-plug-and-play": {
            "require-dev": [
                "vendor-name/package-to-require-dev"
            ]
        }
    }
}

Autoload dev dependencies from plugged packages

When developing a package or library you may need to autoload its dev dependencies:

{
    "extra": {
        "composer-plug-and-play": {
            "autoload-dev": [
                "vendor-name/package-to-autoload-dev"
            ]
        }
    }
}

Contributing

Contributions are welcome. Please open an issue before submitting a pull request so the change can be discussed first.

composer test     # run all tests
composer format   # format code with Laravel Pint (PSR-12)

License

Composer Plug and Play is licensed under the MIT license. See the license file for more details.