Awesome
cpx - Composer Package Executor
Run any command from any composer package, even if it's not installed in your project.
cpx is to Composer what npx is to npm.
Installation
Using Composer, you can install cpx by running:
composer global require cpx/cpx
Usage
You can run a command using cpx by passing through the package name and the command you want to run:
Note: A package name is what you'd use to require the package in your
composer.json
file, e.g.friendsofphp/php-cs-fixer
You can also use constraints to specify a version, e.g.friendsofphp/php-cs-fixer:^3.0
cpx <package-name> <command> [arguments]
# Example: cpx friendsofphp/php-cs-fixer php-cs-fixer fix ./src
If the package only has one command, or the command name is the same as the package's name, you can omit the command from the end:
cpx <package-name> [arguments]
# Example: cpx friendsofphp/php-cs-fixer fix ./src
Behind the scenes, cpx will install the package into a separate directory and run the command, keeping it separate from both your project and global Composer dependencies. Subsequent runs of the same package will use the same installation and run quickly, unless you specify a different version or there is an update to the package available.
As different projects may use different tools to do the same job, cpx provides a set of commands to normalise common tasks, using the packages a project has installed; cpx check
, cpx format
and cpx test
.
For each of these commands, you can continue to pass through additional arguments and flags to the underlying tool as if you were running it directly.
cpx check
cpx check
(or the aliases cpx analyze
or cpx analyse
) runs a static analysis tool on your codebase (e.g. PHPStan, Psalm or Phan).
cpx format
cpx format
(or the alias cpx fmt
) Runs a code formatting tool on your codebase (e.g. PHP-CS-Fixer, Pint or PHP_CodeSniffer).
You can pass the --dry-run
flag to see what changes would be made without actually making them.
cpx test
cpx test
runs a testing framework on your codebase (e.g. Pest, PHPUnit or Codeception).
cpx aliases
cpx aliases
will show a list of popular packages that have been aliased to make them easier to run. You can use these aliases to run a package without needing to remember the full vendor, package and command name.
For example, cpx php-cs-fixer
is an alias for cpx friendsofphp/php-cs-fixer
, and cpx laravel
is an alias for cpx laravel/installer
.
cpx list
cpx list
shows all the packages you have run via cpx and have installed.
cpx update
While cpx will automatically check for updates to a Composer package when you run a command, you can also manually update packages.
cpx update
will update the local version of all packages run via cpx to the latest version, according to their version constraints.
cpx update <vendor>
or cpx update <vendor>/<package>
will update only the specified packages.
cpx clean
cpx clean
will remove all the packages you have run via cpx but haven't used recently. cpx clean --all
will remove all packages regardless of when they have run.
cpx exec and cpx tinker
cpx gives you multiple ways to run PHP code quickly, perfect for running scratch files or quickly running code in your project.
cpx exec <file.php>
will run a plain PHP file.cpx exec -r <raw php code>
will execute the given PHP code.cpx tinker
will open an interactive REPL in the terminal for your project.
When using these commands, you get the following benefits:
- Automatic Autoloaders - When running a PHP file, it will automatically detect and use Composer's autoloader if it exists in the current or a parent directory
- Class Aliasing - If a class is used in the file but the namespace isn't imported, cpx will try to find an appropriate one to alias.
- Laravel Bootstrapping - If the autoloader directory happens to be a Laravel project directory, cpx will bootstrap the application, setting up service providers and such.
- composer_require() - You can use the function like
composer_require('vendor/package')
in the executed script and those packages will be autoloaded into the file.
cpx help
cpx help
will show a list of all the commands available in cpx.
FAQ:
Why not just use global composer?
Installing packages with composer global require
is a great way to install packages that you want to use globally, but it has some downsides:
- You can get conflicts with other global dependencies (especially tooling using common dependencies like
nikic/php-parser
andsymfony/console
) - You might need to switch between versions of the package between runs, but can only have one version installed globally
- You need to remember to update your global packages if you are using them long-term
- You might only use a package's command once, and don't want to install it globally
What kind of one-off commands might I want to run with cpx?
There are a few reasons you might want to run a one-off command with cpx:
- Applying code-style fixes using a tool like
php-cs-fixer
orrector
- Running analysis of your codebase using a tool like
phploc
orphpstan
- Creating files or stubs using a tool like
laravel/installer
Can I use multiple different versions of a tool with cpx?
Yes, cpx will manage the package versions for you, so you can run any version of the package you want.
Why does the source code of cpx have no dependencies?
The code is deliberately written in a way that it doesn't need any dependencies to run, so it has no chance of conflicting with your global composer dependencies if you use them for other things, as this is one of the problems cpx is trying to solve.