Running Composer Scripts

Every project accumulates commands the whole team must run the same way: the test suite, the linter, the asset build, the local dev server. Composer gives those commands a home in composer.json so nobody has to remember the flags:

{
    "scripts": {
        "test": "phpunit --colors=always",
        "lint": ["@php tools/lint.php src", "@php tools/lint.php tests"],
        "fix-cs": "php-cs-fixer fix",
        "serve": "php -S localhost:8000 -t public"
    }
}

Two shapes are accepted. A string runs one command; an array runs several in order, stopping at the first non-zero exit — which is what you want in CI, because a lint failure should abort before tests run. Two conventions inside those strings matter:

• @php resolves to the exact PHP binary Composer itself is running, so a machine with php8.1 on PATH and PHP 8.3 in the project still executes your tool under the project's interpreter. Bare php trusts whatever the shell finds, which is how "works on my machine" gets a second life inside tooling.
• Binary names like phpunit resolve to vendor/bin/phpunit automatically, because scripts run with vendor/bin prepended to PATH. You never type the vendor path.

Running them:

composer test            # bare-name shortcut: any script without a colon works
composer run-script test # the explicit form; the only way when names collide
composer run-script -l   # list every registered script

The shortcut is sugar over run-script, and it has one real edge case: composer dump-autoload, composer validate, and friends are Composer's own subcommands. A script named validate will never win the bare call — the native subcommand takes precedence — so scripts shadowed like this must go through composer run-script validate. Teams that hit this once adopt scripts:check-style prefixes and stop thinking about it.

Scripts do not have to be shell strings. A value naming a PHP static method runs in-process instead of spawning a shell:

{
    "scripts": {
        "fix-cs": "App\\Tools\\CodeStyle::fix"
    }
}

That method receives the Composer\Script\Event which fired: getArguments() returns whatever followed --, getName() the event name, getComposer() the running instance. For it to be found at all, the class must resolve through your autoload rules — the PSR-4 mapping you set up in PSR-4 Autoloading is exactly what makes it loadable, and a callback missing from the classmap dies with a class-not-found error before your command runs.

Two manifest fields make the set discoverable:

{
    "scripts-descriptions": { "test": "Run the full PHPUnit suite" },
    "scripts-aliases": { "phpstan": ["stan", "analyze"] }
}

composer list and composer run -l print your descriptions instead of Composer's default "Runs the ... script as defined in composer.json", and aliases (Composer 2.7+) give everyone a shorter name without renaming the canonical one. composer validate warns when a description or alias points at a script that does not exist.

Script bodies can reference each other with @: "ci": ["@lint", "@test"] runs sibling scripts in order instead of duplicating their commands, and @putenv exports variables for the commands that follow it in the same list — "test": ["@putenv APP_ENV=testing", "@php vendor/bin/phpunit"]. Every behavior is then defined exactly once, and changing the test invocation changes every caller. That single-definition property is the real argument for scripts over a README full of shell snippets: documentation drifts, while an entry in scripts is executed by humans and CI through the same string.

Arguments pass through an explicit -- boundary:

composer test -- --filter=OrderTest --testdox
# runs: phpunit --colors=always --filter=OrderTest --testdox

Everything after -- is appended verbatim to the script's command. Exit codes propagate the same direction: composer test exits non-zero when PHPUnit does, so the same script works in a pre-push hook, in CI, and on a teammate's terminal with no re-implementation. That propagation is also why scripts are the automation primitive rather than a wiki page of shell snippets — and why a hook that exits non-zero can abort an install, as the next chapter shows.

One bound applies to every script you write: Composer kills a process that runs past 300 seconds by default. A dev server or a long suite dies mid-run unless you raise config.process-timeout, export COMPOSER_PROCESS_TIMEOUT=0 for one terminal, or list Composer\Config::disableProcessTimeout as the first entry of a single script's array.

Beyond named scripts, Composer defines events that fire during its own operations. Declare a script with an event's name and it runs automatically at that moment — this is how applications keep working directories healthy without a human remembering a step.

The events you will actually use:

Two of those rows carry surprises interviewers like. post-update-cmd is not "updates only": an install with no composer.lock has to resolve versions like an update, so a brand-new clone fires post-update-cmd rather than post-install-cmd. And post-autoload-dump fires when you run composer dump-autoload by hand, which is what makes it the right home for anything derived from the installed package set.

The canonical example is Laravel's cache-warmup dance, which any templated app repeats:

{
    "scripts": {
        "post-autoload-dump": [
            "@php artisan package:discover",
            "@php artisan horizon:terminate"
        ]
    }
}

Every composer install, composer update, and composer dump-autoload now refreshes the discovered-packages cache — nobody can forget the step, because there is no step to forget. Choosing the event is a correctness question: caches derived from installed packages belong on post-autoload-dump (it fires even when you re-dump without installing), while behavior that must differ between "new tree from the lock" and "freshly resolved tree" splits across post-install-cmd and post-update-cmd.

Hooks are not a black box. You can run any of them on demand, which is how you debug a broken one without reinstalling anything:

composer run-script post-install-cmd -- --check

--check reaches the handler as an argument — a shell script sees it in $argv, a PHP callback through $event->getArguments() — so the same hook doubles as a manual repair tool.

Three boundaries keep hooks sane:

• Only the root package's scripts run. Composer does not execute lifecycle scripts declared by dependencies — a package you install cannot run arbitrary hooks in your project. (Plugins are a separate, explicit trust decision gated by allow-plugins, covered in Initializing a Project with Composer.)
• A failing hook fails the operation. post-install-cmd exiting non-zero aborts the install, which is a feature in CI and a puzzle on a laptop when a stale cache makes the hook crash. The escape hatch is composer install --no-scripts — dependencies install, hooks do not run, and you fix the script separately.
• pre-* hooks must be self-contained. Composer's own guidance is that no Composer-managed dependency is guaranteed to exist before install or update runs, so a pre-update-cmd that autoloads a class from vendor/ fails exactly when you are trying to install it. Keep pre-hooks to root-package code and plain shell; put anything that needs vendor/ after the work instead.

Hooks inherit the same execution rules as named scripts — @php resolves to Composer's interpreter and vendor/bin is on PATH — and --no-scripts suppresses every hook for that run across install, update, and dump-autoload, not just the one that bit you.

Migration scripts deserve a warning label. Running phinx migrate or artisan migrate on post-install-cmd sounds diligent until the first deploy where a migration is incompatible with the code still running — production takes the downtime at the worst moment. Migrations are a deliberate, observable deploy step for a reason; let hooks handle caches and discovery, not schema.

One script, two events — the standard way to deduplicate hooks without losing the distinction between them. Composer appends the triggering event's name to the command line, so a hook can branch on $argv:

{
    "scripts": {
        "post-install-cmd": ["@php tools/cache-rebuild.php"],
        "post-update-cmd":  ["@php tools/cache-rebuild.php"]
    }
}

<?php
// tools/cache-rebuild.php
$event = $argv[1] ?? '';
if ($event === 'post-update-cmd') {
    echo "New dependency tree resolved — invalidating shared cache\n";
    invalidateRemoteCache();
}
rebuildLocalCache();

Run composer update and the script announces the tree change; a plain install stays quiet but still rebuilds. The event name arriving as an argument is Composer's contract — post-install-cmd when install ran, post-update-cmd when update did — and it is the difference between "clear a cache" and "react to resolution." A PHP callback gets the same information through $event->getName().

Composer also exports environment variables that hooks read directly, the most useful being COMPOSER_DEV_MODE:

<?php
$dev = getenv('COMPOSER_DEV_MODE') !== '0'; // false when the run used --no-dev

That single variable separates deploy behavior from developer behavior without parsing command lines: a post-install-cmd that warms a dev toolbar checks it and stays silent on production installs. It is set for install, update, and dump-autoload, carrying the value of the last real install or update. COMPOSER_BINARY (the path to the composer executable) lets a script shell back into Composer without guessing whether the machine calls it composer, composer.phar, or php composer.phar.

Where appended arguments land is controllable too. Composer 2.8 appends whatever follows -- to the end of each command in the array, and two markers override that: @no_additional_args keeps a command argument-free, @additional_args places them exactly where you want.

{
    "scripts": {
        "run-commands": [
            "echo checking @no_additional_args",
            "phpunit @additional_args --colors=always"
        ]
    }
}

composer run-commands -- --filter=OrderTest now runs a bare echo and a phpunit --filter=OrderTest --colors=always. When a command needs real flags of its own — declared options, --help output, typed arguments — register a Symfony Console command class instead: a class ending in Command can be assigned directly to a script name (Composer 2.5+), and composer my-cmd --arbitrary-flag works with no -- boundary at all. The trade-off is that it runs against Composer's bundled console, not the version your project requires.

Portability is the last piece, and it is where hand-rolled shell habits break. "test": "phpunit && php-cs-fixer fix" works on Linux and macOS and dies on Windows, where scripts execute through cmd.exe and &&-chaining plus POSIX quoting are unreliable. The portable form is the array — each entry is its own process, Composer handles sequencing and the stop-on-failure rule:

"ci": ["@php tools/lint.php", "@composer test", "@php tools/coverage-check.php"]

Inside that list, @php pins the interpreter and @composer re-enters Composer itself (used here to run the test script from inside ci — the @ prefix is what distinguishes "run the composer script named test" from "run a binary named composer"). You cannot chain two Composer or PHP commands inside one string with &&; the array is the supported spelling of "and then."

Scripts written this way — arrays, @php, event-name branching — run identically on a developer's laptop, the CI container, and the production deploy box, which is the whole point of putting the automation in the manifest instead of a README. "Where do you put project automation in a PHP repo?" is a fair interview question, and the answer is Composer scripts: name @php, the -- boundary, and post-autoload-dump, and you have shown you have built one that survived a team. The other half of the manifest decides what those hooks install — that is Version Constraints and Stability.