Development

How to Use Composer Scripts for Common Development Tasks

Use Composer scripts to give a PHP project one documented way to run common tasks. Define commands in the root composer.json, use @php for the selected PHP executable, and compose small checks into a verification command.

The benefit is shared behavior between a developer's terminal and CI. A command that only works through someone's shell history is not a reliable project interface.

Use Composer scripts for repeatable checks

This example needs PHP 8.1+ and Composer 2. Create composer.json:

{
  "name": "example/project-tasks",
  "require": {"php": ">=8.1"},
  "scripts": {
    "lint": "@php -l app.php",
    "smoke": "@php tests/smoke.php",
    "verify": ["@lint", "@smoke"]
  },
  "scripts-descriptions": {
    "verify": "Check syntax and the example greeting behavior"
  }
}

Create app.php:

<?php

declare(strict_types=1);

/** Builds the application's example greeting. */
function greeting(string $name): string
{
    return 'Hello, ' . $name;
}

Create tests/smoke.php:

<?php

declare(strict_types=1);

require dirname(__DIR__) . '/app.php';

if (greeting('Mike') !== 'Hello, Mike') {
    fwrite(STDERR, "Greeting behavior changed.\n");
    exit(1);
}

fwrite(STDOUT, "Greeting check passed.\n");

Run composer run-script verify. The syntax check and smoke check should both succeed. Change the expected greeting and rerun: verification should fail. A check that never demonstrates failure has weak evidence behind it.

The Composer scripts documentation explains script references, PHP execution, and event behavior.

Keep commands narrow and honest

The example's lint checks one file. It does not claim to lint the entire repository. Expand the file set deliberately or use an existing project tool once the application grows.

Likewise, the smoke check proves one behavior. It does not establish database compatibility, endpoint authorization, or deployability. Name commands according to the evidence they produce.

@php keeps script execution aligned with the PHP binary used to run Composer. It does not make that binary match the web server. Check the runtime used by both local tooling and CI when a version mismatch appears.

Distinguish manual tasks from lifecycle hooks

A named task such as verify runs when requested. A lifecycle event such as post-install-cmd runs as part of another operation. Avoid placing destructive database changes, customer emails, or production deployment inside an installation hook.

A developer may run installation in a test container, an audit environment, or an offline build. Hidden production side effects make those legitimate uses risky.

Composer's command-line documentation describes --no-scripts. Decide explicitly where scripts are required and where a restricted build disables them. Do not assume a skipped hook still produced its generated files.

Handle arguments deliberately

When a task accepts arguments, document a complete invocation such as composer run-script smoke -- argument. Confirm how the target command receives them. An argument added to an aggregate task may be passed in ways that are not meaningful to every child task.

Avoid shell-specific pipelines when a small PHP script can implement the behavior portably. When a shell is necessary, name the shell and the operating-system expectation in the project instructions.

Make CI use the same interface

Have CI call composer run-script verify after dependency installation, rather than duplicating the underlying command list in a second location. Add environment-specific setup outside that shared verification task.

For a legacy project, introduce one useful check first. The PHPStan adoption guide shows the same incremental principle for static analysis: define a manageable starting point and improve it without hiding existing debt.

Should Composer become my deployment system?

It can invoke a deployment tool, but the authorization, environment selection, credentials, and rollback still need explicit design. Keeping ordinary development verification independent from deployment makes both easier to reason about.

If your team's commands have drifted between laptops and CI, review the PHP delivery workflow around a single reproducible change.