Download the PHP package wpelevator/phpcs-parallel without Composer

run-parallel

Run a list of commands, or one command per matched path, in parallel.

run-parallel is useful for running Composer scripts concurrently — think npm-run-all for PHP — and for monorepos where each package has its own tool config. It discovers paths, renders one command per path, and executes those commands with prefixed output.

Install

The package declares Composer replacements for the earlier package name wpelevator/phpcs-parallel so dependent packages can move to wpelevator/run-parallel without installing duplicate copies.

Usage

At its simplest, pass each command with --command:

Each command becomes its own task, and tasks run in parallel with prefixed output, a per-task summary, and the highest exit code as the result. Repeat --command when you want npm-run-all style behaviour. See Composer scripts for running named scripts concurrently.

For monorepos, provide a path pattern and a command template instead. One task is created per matched path:

Tasks run in parallel by default, one process per CPU core. Use --processes to control the concurrency (--processes=1 runs serially):

Use --cwd when a tool should run from the matched package directory:

Repeat --command with --path-pattern to run multiple commands for each matched path:

By default, labels for multiple commands per matched path include both the matched path and the command, such as foo:composer-validate and foo:composer-test.

When --cwd is set, use {path | realpath} for file paths that must still point back to the matched file:

Use --label when you want custom output prefixes:

Options:

Path patterns

Patterns use glob semantics: * and ? match within a single path segment and never cross /, while ** matches any number of segments. Character classes like [0-9] and [!0-9] are supported.

Use --dry-run to preview which paths matched and what will run:

Template variables

Filters

Variables can be piped through filters with |. Filters apply left to right, so {path | dirname | basename} takes the directory of the matched path, then its last segment.

Example outputs below assume the matched path is packages/foo/phpcs.xml.dist and run-parallel was invoked from /repo:

Referencing an unknown variable or filter in a template is an error and fails the run. Custom filters and variables can be added via a config file.

Commands are executed directly as argv, not through a shell. Pipes, redirects, and shell expansion are not interpreted.

Binary resolution

The first word of each command is resolved through the PATH environment variable, which child processes inherit from run-parallel. When run-parallel runs as a Composer script, Composer prepends the project's vendor/bin directory to PATH for the duration of the run, so bare binary names like phpcs or phpstan resolve to the project-local binaries — even when --cwd points at a package subdirectory, because the prepended vendor/bin path is absolute.

When invoking vendor/bin/run-parallel directly from the shell, PATH is not modified, so bare names resolve to whatever is installed globally. In that case, reference project-local binaries by path:

Working directory

By default, every command runs in the directory where run-parallel was invoked. Use --cwd to run each command from a different directory — typically the matched package directory via --cwd='{path | dirname}'. The template is rendered once per task, and a relative result is resolved against the invocation directory.

--cwd changes the child process working directory, but template variables are still rendered relative to the original invocation directory. Use {path | realpath} when the child process needs an absolute path.

Configuration

Use --config=run-parallel.php to load custom filters, variables, and default option values.

Then run:

CLI options override config defaults, so you can still replace individual values:

The command default also accepts a list. Without path patterns, each command becomes its own task. With path patterns, each command runs once per matched path:

Custom filters receive the current value, the current task, and the invocation working directory:

Examples

PHPCS

Run PHPCS once per package ruleset:

Run PHPCS in parallel and pass PHPCS options directly in the command template:

If your project uses multiple PHPCS config names, repeat --path-pattern:

PHPCBF

PHPStan

PHPUnit

Composer

The command template accepts any Composer invocation, not just composer test:

Run a named Composer script the same way:

Composer scripts

Run existing Composer scripts in parallel by wrapping them in a run-parallel script, npm-run-all style:

Now composer check runs all three concurrently with prefixed output and a summary, and fails if any of them fail.

Composer adds vendor/bin to PATH when running scripts, so both run-parallel and the binaries referenced in commands can use bare names here (see Binary resolution):

Development

Run the same checks used by CI:

Run a specific test suite:

Generate PHPUnit coverage reports (requires Xdebug or PCOV):

Coverage output is written to the terminal, tests/coverage/clover.xml, and tests/coverage/html.

Use the self test to run all checks concurrently:

Why not …?

• phpcs --parallel, PHPStan workers, ParaTest — these parallelize within one config. run-parallel parallelizes across configs (one run per package), and the two compose: each run-parallel task can itself use the tool's own parallelism.
• veewee/composer-run-parallel — runs named Composer scripts concurrently, like run-parallel's command-list mode, but has no path discovery or per-path command templating.

Notes

• Dependency directories are skipped during discovery: .git, vendor, node_modules, bower_components.
• Child process output is streamed through Symfony Console and prefixed with the task label; labels are colored when the output is a terminal.
• A per-task summary with durations and exit codes is written to stderr after the run.
• The command returns the highest child exit code for normal tool failures. Runtime/tooling errors are promoted to at least exit code 3.
• On SIGINT/SIGTERM (e.g. Ctrl+C), running child processes are stopped before exiting (requires the pcntl extension; standard on Linux/macOS CLI builds).
• File-modifying tools are safe only when matched paths do not overlap.

License

This project is open-sourced under the MIT License. See LICENSE for details.