Composer Scripts

When to use

• The user wants a single script that runs several tools in sequence, such as lint then test then static analysis.
• The user wants to run a task automatically after a Composer install or update, such as clearing a cache or dumping config.
• The user wants a short, named command (like test or lint) that runs a longer tooling invocation.

When NOT to use

• Do not use Composer scripts as the primary orchestrator for a complex, multi-stage build with parallelism and dependencies between targets.
• Do not put application runtime logic in a Composer script; scripts run at the developer or CI command line, never per HTTP request.

Core guidance

• Compose scripts by referencing them with @ — Build a pipeline by listing sub-commands in an array and calling other scripts with an @ prefix, e.g. a check script that runs @lint, @analyse, and @test.
• Subscribe automation to lifecycle events — Attach automation to the exact lifecycle event it belongs to, using post-install-cmd, post-update-cmd, or post-autoload-dump rather than expecting developers to run it by hand.
• Define named scripts under the scripts key — Add commands under the top-level scripts key in composer.json, mapping a name to a command or an array of commands, then run them with composer <name>.

Quick recipe

1. Add one script per tool under scripts, e.g. "lint", "analyse", and "test", each pointing at its binary in vendor/bin. (verify: composer test runs the test suite on its own)
2. Add a "check" script whose array calls @lint, @analyse, and @test in order so one command runs the whole gate. (verify: composer check runs lint, analyse, and test in sequence and stops on the first failure)
3. Call composer check as the single quality step in the CI workflow. (verify: The CI job runs composer check and fails the build if any sub-step exits non-zero)

Best practices

• Add a scripts-descriptions block so composer run-script --list explains what each script does for new contributors
• When a script needs real PHP logic, reference a static method callable ("App\\Composer\\Hooks::postInstall") instead of packing logic into a shell string

Anti-patterns

See references/anti-patterns.md.

Common mistakes

1. Script name collides with a Composer command — Naming a script after a built-in command like install or update silently overrides that command. Fix: Name scripts with task-specific verbs (test, lint, check) and never reuse a reserved Composer command name.
2. Post-install hook fails under --no-dev — A post-install-cmd that calls a dev-only tool crashes when production runs composer install --no-dev. Fix: Guard dev-only steps so they skip when the tool is missing, or move them to a dedicated dev-only script not bound to install.
3. Chained shell command hides a failure — Joining sub-commands with a shell pipe or a stray || true can make a failing step report success. Fix: List sub-commands as separate array entries so Composer stops on the first non-zero exit, and avoid || true on quality gates.

Version notes

• Composer 2 keeps run-script and adds exec (PHP >=7.4) — Composer 2 continues to run named scripts via composer <name> or composer run-script <name>, and adds composer exec to run vendor binaries without defining a script.

Security

• Not applicable — no I/O, auth, or untrusted input.

Testing

• Activation and decision behavior are verified in eval/scenarios/composer/scripts.yaml.

Additional resources

• references/anti-patterns.md
• references/core.md
• references/examples.md
• references/pitfalls.md
• references/recipes.md
• references/version-differences.md

Knowledge graph

Related: composer/dependency-management, psr/psr12-coding-style