Using Composer platform-check to Catch PHP Version Mismatches Early

The problem: silent PHP mismatches break builds

When a project declares a minimum PHP version or required extensions in composer.json, a developer can run composer install on a machine that appears to satisfy those constraints—yet the build later fails in CI or production because the PHP version is too low or an extension is missing. The failure surfaces only after dependencies are downloaded, wasting time and eroding confidence in the deployment process.

Thesis: run composer platform-check early to fail fast

Composer’s platform-check command evaluates the local PHP environment against the platform requirements (php and ext-*) declared in composer.json. If anything is missing or insufficient, the command exits with a non‑zero status and prints a clear message, allowing teams to stop the workflow before any dependency resolution occurs.

How platform-check validates your environment

The command reads the require and require-dev sections of composer.json, extracts the platform constraints, and compares them to the currently active PHP interpreter and the list of statically loaded extensions (those visible via php -m). It does not inspect extensions that are loaded at runtime with dl() or via php.ini extension directives that are conditionally included.

When the environment satisfies all constraints, platform-check exits with code 0 and prints nothing (or a brief success message if verbose flags are used). If a constraint is violated, it writes a line such as PHP version 8.0.2 does not satisfy ^8.1 or Missing extension json and returns a non‑zero exit code.

Worked example: catching a missing JSON extension

1. Create a test project directory and add a composer.json that requires PHP 8.1 and the JSON extension:

{
  "require": {
    "php": "^8.1",
    "ext-json": "*"
  }
}

1. Ensure the local PHP version is 8.0 (or any version < 8.1) and that the JSON extension is not installed. On a Debian‑based system you could simulate this by temporarily renaming the extension file, but the exact steps depend on your environment.
2. Run the check from the project root:

composer platform-check

You will see output similar to:

PHP version 8.0.2 does not satisfy ^8.1
Missing extension json

The command returns exit code 1. Fixing the issue—by upgrading PHP to 8.1+ and installing the JSON extension (e.g., sudo apt-get install php-json on Ubuntu)—and re‑running the command yields no output and exit code 0, indicating the platform constraints are satisfied.

Trade‑offs and limitations

• Scope: Only statically loaded extensions are examined; extensions loaded via dl() or through conditional php.ini inclusions are invisible to the check.
• Version requirement: Available starting with Composer 2.0. Running the command on Composer 1.x produces a “command not found” error, so teams must upgrade Composer first.
• No side effects: The command does not modify composer.lock or install packages, making it safe to run in any context, including CI pipelines.

Actionable closing

• Add composer platform-check as an early step in your local development setup scripts and CI pipelines (e.g., as the first job in a GitHub Actions workflow).
• Use the --no-dev flag when you want to ignore development‑only platform requirements, such as ext-xdebug.
• Treat a non‑zero exit code as a hard failure; do not proceed to composer install until the check passes.
• Periodically review the platform section of composer.json to ensure it reflects the true runtime needs of your project.