Automating Post‑Install Tasks with Composer Scripts

The repetitive manual step problem

After every composer install or composer update many projects require the same follow‑up commands: clearing caches, running database migrations, generating frontend assets, or warming up opcache. Doing this manually leads to drift between environments and wastes developer time.

How Composer scripts solve it

Composer includes a scripts section in composer.json that lets you bind shell commands or PHP callables to lifecycle events such as pre-install-cmd, post-install-cmd, pre-update-cmd, and post-update-cmd. When Composer reaches the corresponding event it executes the listed commands automatically, using the same environment and privileges as the Composer process itself.

Defining scripts in composer.json

Inside the scripts object map an event name to either a string, an array of strings, or a PHP callable. You can use the special placeholder @php to refer to the project’s PHP binary, chain commands with & (Unix) or &&, and reference executables installed by dependencies via vendor/bin.

Worked example: Laravel migrations and cache clear

Assume a typical Laravel application. Add the following to composer.json:

{
    "scripts": {
        "post-install-cmd": [
            "@php artisan migrate --force",
            "@php artisan cache:clear"
        ],
        "post-update-cmd": [
            "@php artisan migrate --force",
            "@php artisan cache:clear"
        ]
    }
}

After saving the file, run composer install in the project directory (no special permissions required; the command runs with the user’s privileges). Composer will download dependencies, then execute the two artisan commands. You should see output similar to:

Migration table created successfully.
Cache cleared successfully.

If you only want to test the script without a full dependency install, execute:

composer run-script post-install-cmd

This runs the same commands immediately, confirming that the event is wired correctly.

Trade‑offs and safety considerations

• Privilege level: Scripts inherit the permissions of the Composer process. A compromised package could therefore run arbitrary code on your machine or CI agent. Keep the scripts minimal, avoid executing user‑provided input, and review dependencies before running them in production.
• Cross‑platform compatibility: The examples use Unix‑style operators (&, &&) and the @php placeholder, which works on Windows as well. However, if you need Windows‑specific commands (e.g., call or cmd /c), provide separate scripts or use cross‑platform tools like npm scripts.
• Visibility: Because scripts run automatically, it can be surprising when a composer install triggers a migration. Document the scripts in your project’s README and consider adding a composer.json comment explaining their purpose.

Getting started and verification

1. Open a terminal in your project’s root directory.
2. Edit composer.json and add a scripts block as shown above.
3. Save the file.
4. Run composer install (or composer update if you only changed dependencies).
5. Observe the output; the commands listed under post-install-cmd should appear after the dependency installation step.
6. Optionally, run composer run-script post-install-cmd to verify the script works independently.

If the expected output does not appear, check that:

• the event name matches exactly (case‑sensitive).
• the commands are executable and present in vendor/bin or in your PATH.
• there are no syntax errors in the JSON (trailing commas, missing quotes).

Actionable closing

Adding a scripts section turns repetitive post‑install chores into a reliable, version‑controlled automation step. Start with a single, safe command (e.g., cache clear) to gain confidence, then expand to migrations or asset builds as needed. Commit the updated composer.json so every developer and CI pipeline receives the same behavior, and periodically review the script contents as part of your dependency‑security routine.