CPX 2.0: The Composer Package Executor for PHP

What Is CPX?

cpx is a CLI tool that lets you run a command from any Composer package without adding that package to your project's composer.json. If you've ever reached for composer global require and hit a dependency conflict, cpx solves that by installing each package into its own isolated directory and reusing that installation on repeat runs.

The analogy is intentional: cpx is to Composer what npx is to npm.

Running a Package Without Installing It

Pass the package name followed by the command and any arguments. Version constraints are supported:

cpx friendsofphp/php-cs-fixer php-cs-fixer fix ./src
cpx friendsofphp/php-cs-fixer:^3.0 php-cs-fixer fix ./src

When a package has a single binary, or its binary name matches the package name, you can omit the command:

cpx friendsofphp/php-cs-fixer fix ./src

You can also point cpx at a local directory instead of a package name, which is handy when developing a package locally:

cpx ../my-package --version

Local Binaries Win by Default (New in 2.0)

This is the most significant behavioral change from 1.x. cpx now walks up from the current directory to find the nearest Composer project and prefers the binary from that project's bin-dir:

cpx pint                  # runs vendor/bin/pint when the project has it
cpx phpunit --filter=Foo  # runs vendor/bin/phpunit when present
cpx laravel/pint:^2.0     # uses local pint only if it satisfies ^2.0

When no matching local binary exists, cpx falls back to an isolated installation. Pass --skip-local to force the isolated copy regardless.

User-Defined Aliases

Version 1.x shipped a hardcoded list of shortcuts. That list is gone in 2.0—you define your own:

cpx alias phpstan/phpstan phpstan
cpx alias laravel/pint          # defaults to the short name "pint"

Aliases are stored in ~/.cpx/. Use cpx aliases to list them and cpx unalias <name> to remove one. cpx installed lists packages you have run through cpx, and cpx clean removes ones you haven't used recently (--all removes everything).

Running PHP Files, Gists, and a REPL

cpx exec and cpx tinker cover scratch files and quick one-offs:

cpx exec script.php
cpx exec -r 'echo PHP_VERSION;'
cpx exec https://gist.github.com/user/id
cpx tinker

Both commands detect Composer's autoloader, alias unimported classes where possible, and fully boot a Laravel or Symfony application when one is present. Pass --no-boot to skip that. Inside these scripts, cpx_require() pulls in a package on demand:

cpx_require('nesbot/carbon');
echo Carbon\Carbon::now();

In a Laravel project with laravel/tinker installed, cpx tinker delegates to php artisan tinker. Everywhere else it opens a PsySH shell.

Agent-Aware JSON Output

cpx detects non-interactive environments—redirected stdin, --no-interaction, or an AI agent identified via laravel/agent-detector. In that mode, management commands return structured JSON instead of formatted terminal output:

{
  "success": true,
  "errors": [],
  "summary": {
    "packages": [
      { "name": "laravel/pint", "last_run": "2024-01-02 03:04:05" }
    ]
  }
}

Pass --json to get the same output from an interactive terminal.

Installing CPX 2.0

CPX 2.0 requires PHP 8.3 or higher. Install it globally and ensure Composer's global bin directory is on your PATH:

composer global require cpx/cpx

If you are on 1.x, review the 1.x to 2.x upgrade guide before upgrading.

Key Takeaways

• cpx runs Composer package binaries in isolation—no project or global dependency conflicts.
• 2.0 prefers local project binaries by default; use --skip-local to override.
• The hardcoded alias list is replaced by user-defined aliases stored in ~/.cpx/.
• cpx exec and cpx tinker support PHP files, remote Gists, and on-demand package loading via cpx_require().
• Non-interactive and AI-agent environments receive structured JSON output automatically.
• Requires PHP 8.3+; now a first-party laravel/cpx package.

Source: CPX: The Composer Package Executor for PHP — Laravel News