CPX 2.0: The Composer Package Executor for PHP

What Is CPX?

CPX is a CLI tool that does for Composer what npx does for npm: it lets you run a binary from any Composer package without installing that package into your project or your global Composer setup. Each package gets its own isolated directory, so dependency conflicts between globally installed tools become a thing of the past. Repeated runs of the same version reuse the cached installation, and CPX checks for updates automatically.

CPX 2.0 is now a first-party laravel/cpx package maintained by the Laravel team. It requires PHP 8.3 or higher.

Running a Package Without Installing It

Pass the package name followed by the command and any arguments. Version constraints work exactly as they do in composer.json:

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 exposes a single binary, or the 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, which is handy when developing a package:

cpx ../my-package --version

The directory must contain a valid composer.json and an installed vendor/autoload.php. CPX runs the declared binary directly from that checkout without copying or caching anything.

Local Binaries Win by Default

This is the most significant behavior change from 1.x. CPX now walks up from the current directory to find the nearest Composer project and prefers its vendor/bin binaries:

cpx pint                  # runs vendor/bin/pint when present
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. To force the isolated copy regardless, pass --skip-local.

User-Defined Aliases

The hardcoded shortcut list from 1.x is gone. You now define your own aliases:

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 shows every package you have run through CPX, and cpx clean removes packages not used recently (--all clears everything).

Running PHP Files, Gists, and a REPL

cpx exec and cpx tinker handle scratch files and quick experiments:

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

Gist support downloads the file and runs it in your current directory context. In a Laravel project, cpx tinker hands off to php artisan tinker; elsewhere it opens a PsySH shell with your project booted.

Inside these scripts, cpx_require() pulls in a Composer package on demand:

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

AI-Agent-Aware 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:

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

Package runs stream only the underlying tool's output. Pass --json to get the same format in an interactive terminal.

Installing CPX 2.0

composer global require cpx/cpx

Make sure Composer's global bin directory is on your PATH.

Key Takeaways

• CPX runs any Composer package in isolation—no global dependency conflicts.
• Local project binaries take priority by default; use --skip-local to override.
• User-defined aliases replace the old hardcoded shortcut list.
• cpx exec supports local files, inline code, and GitHub Gists.
• cpx tinker boots your Laravel or Symfony project automatically.
• Non-interactive and AI-agent environments receive clean JSON output.
• Requires PHP 8.3+; install with composer global require cpx/cpx.

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