Composer Run Parallel Laravel Package

Getting Started

Add veewee/composer-run-parallel as a dev dependency:

composer require --dev veewee/composer-run-parallel

That’s it—no extra setup needed. The package installs a single command: composer run-parallel, which replaces composer run in scripts where concurrency is desired.

First use case: Define a multi-step workflow (e.g., lint, test, build) that can run in parallel. In composer.json, extend your scripts:

{
  "scripts": {
    "lint": ["php-cs-fixer fix --dry-run", "phpstan analyse"],
    "test": ["phpunit", "pest"],
    "build": ["composer lint", "composer test"],
    "ci": "composer run-parallel lint test build"
  }
}

Then run:

composer run-parallel ci

All three top-level tasks (lint, test, build) execute concurrently. Each group (lint’s two commands) runs sequentially within its task, but tasks themselves run in parallel.

Implementation Patterns

• Task grouping for pipeline stages: Model CI steps (e.g., lint, test, typecheck, build) as top-level Composer scripts and invoke them in parallel via run-parallel.
• Script aliasing for speed vs. reliability: Keep slow but stable composer ci (sequential) for local dev, and use composer run-parallel ci-fast for CI runners.
• Phased workflows: Combine sequential and parallel stages using nested commands:

  {
    "scripts": {
      "format": "php-cs-fixer fix",
      "analyze": ["phpstan", "psalm"],
      "unit": "phpunit --group unit",
      "integration": "phpunit --group integration",
      "pre-commit": "composer format && composer run-parallel analyze unit integration"
    }
  }
  

• Monorepo orchestration: Run parallel tasks per package/subdir using phpscs-style dispatching:

  "ci": [
    "cd services/auth && composer run-parallel lint test",
    "cd services/api && composer run-parallel lint test"
  ]
  

Gotchas and Tips

• Output interleaving: Parallel output is buffered per task, so each task’s output appears in full blocks (not interleaved lines). This improves readability but may delay visible progress—add --debug to see real-time execution.
• Exit code semantics: The entire run fails if any task fails (non-zero exit). Use || true only for optional tasks (e.g., "lint:optional": "phpstan --allow-non-zero || true"), but avoid it in critical pipelines.
• Beware of shared resources: If tasks write to the same file (e.g., var/cache/), ensure proper locking or avoid parallelizing those steps—this tool doesn’t coordinate I/O.
• Windows compatibility: Uses proc_open() and POSIX-style shell; works via PowerShell/Cygwin but avoid && inside task names. Prefer arrays for multi-command scripts:

  "lint": ["phpcs", "php-cs-fixer"]
  

• Debugging: Set COMPOSER_RUN_PARALLEL_DEBUG=1 to get timing breakdown per task.
• Extensibility: Doesn’t hook into composer run—you must explicitly use run-parallel. This preserves backward compatibility but requires updating scripts maps. Consider using a "lint-parallel": "composer run-parallel lint" alias for gradual adoption.