Himanshu SharmaSoftware engineer
Let’s talk

Composer · Lesson 10 of 15

Composer scripts: repeatable checks for a PHP package

Turn the book-label check into a Composer script and understand explicit commands, lifecycle events and code execution.

12 minChecking and maintaining a projectUpdated 14 November 2026

Awaiting technical review. This lesson is readable but not yet listed in search engines.

By the end of this lessonRun the existing PHP check through Composer and distinguish a root script from dependency scripts.

After this lesson you can give a PHP project a predictable check command and explain the trust boundary around Composer scripts. You will use the existing book-label behaviour check rather than introduce a test framework before understanding what the command does.

Make the useful command easy to find

The library manifest already contains a scripts field. This JSON fragment is its value:

json
{
  "check": "@php tests/check.php"
}

A developer does not need to remember the check file's path once the project documents a stable command. Run it inside the library:

bash
composer run check

Example output captured on 2026-11; yours will differ (selected lines):

text
> @php tests/check.php
Label check passed

The named script launches the same PHP check created earlier. Composer is organising the task, not inventing a new testing language. The check still compares an actual result with an expected string and exits unsuccessfully on a mismatch.

The @php placeholder is important on machines with several PHP installations. It points to the PHP executable used to run Composer, instead of relying on a separate shell lookup of a bare php command. This does not prove that the deployment server uses the same interpreter; platform verification remains a separate responsibility.

Distinguish explicit scripts from events

A custom name such as check runs when you request it. Composer also supports lifecycle event names that connect scripts to dependency operations. The official Composer Scripts documentation explains the event sequence. Before adding automatic hooks, ask whether the action truly belongs to every occurrence of that event.

For example, a metadata-generation task may be appropriate after an autoload regeneration in a particular project. A destructive database reset would not be a sensible surprise during routine installation. This course uses an explicit check command so the action remains visible to a beginner and needs no database or application secrets.

Do not assume installing a package means Composer automatically runs every ordinary script in that package's manifest. Root-project scripts and dependency metadata have different roles. Our shop consumes the library's class; it does not inherit the library author's check command as an automatic installation task.

Keep checks predictable

A useful check should have an understandable success condition and a meaningful failure exit. The explicit conditional in our PHP file makes that boundary visible. Printing a success message without testing anything would create confidence without evidence.

Avoid hiding many unrelated operations behind one short script name. A check that also formats source, changes dependencies and deploys the application is difficult to run safely. Separate tasks when their consequences differ, and document the intended sequence in the project instructions.

Scripts can eventually coordinate linting, tests and other local tools, but introduce each tool deliberately. If a command relies on a development dependency, that dependency must be installed in the environment where the script runs. A production installation that omits development tools cannot be expected to run development checks unchanged.

Understand what disabling scripts means

This verified command installs dependencies without running root scripts or activating plugins:

bash
composer install --no-scripts --no-plugins

These are separate switches because scripts and plugins are separate execution mechanisms. Disabling them can be useful while inspecting an unfamiliar project, but it is not a complete security sandbox. Installed PHP code can still run when you later execute the application.

Skipping scripts can also leave a legitimate project missing generated files that its setup expects. Record that you skipped them, inspect what they would do and restore necessary preparation intentionally. Do not present an installation with skipped steps as equivalent to a fully prepared application without checking the project's requirements.

Common mistakes

A script path is usually interpreted in the root project's context. Do not copy a script from another directory layout and assume it can find its files. Keep the source file path and manifest definition in agreement.

Another mistake is treating a script as trusted because it sits in JSON. It is still an instruction to execute code. Review shell commands, PHP callbacks and event hooks before running Composer in unfamiliar source trees, and use normal user privileges.

Exercise

The shop installs the book-label package. Does that installation automatically run the library's check script? Explain how you would verify the library itself and how the shop should verify its own use of the library.

Show the answer

The dependency's ordinary check script does not become a root installation script. Run the check in the library source project to verify its behaviour. Give the shop its own check of the public API it uses, because successful library testing does not prove the consumer integrated it correctly.

Continue learning

Previous: Composer dump-autoload: regeneration and production maps

Next: Composer diagnostics: platform checks and dependency questions

Related: Composer manifests and locks: intent versus resolution

Related: Composer PSR-4: loading the bookshop library

Key points

  • A named script gives collaborators a repeatable command.
  • The @php placeholder selects the PHP process used by Composer.
  • Scripts execute code and must be reviewed before use.

Check yourself

1. What does @php mean in this script?
2. Are ordinary scripts from dependency manifests run as root project scripts?
3. Does --no-scripts also disable plugins?