Composer Platform Configuration: How to Catch PHP Version Mismatches Before Deployment

php -m

You can also inspect the configuration used by the CLI:

php --ini

These commands are useful because PHP installations can differ between environments. For example, the command-line PHP executable may use a different configuration from PHP-FPM.

If a deployment uses PHP-FPM, a container, or another execution environment, ensure that the checks run against the runtime that actually serves the application.

For an application requiring the intl extension, you can declare the requirement in composer.json:

{
    "require": {
        "php": "^8.3",
        "ext-intl": "*"
    }
}

This declaration allows Composer to consider the extension during dependency resolution and platform validation.

The wildcard means that Composer does not enforce a specific extension version through this requirement. It does not mean the extension is optional.

If the extension is missing, install and enable it in the target environment rather than attempting to bypass the platform check.

Enabling Composer's Platform Check

Composer can generate a platform-check file that verifies certain runtime requirements when Composer's generated autoloader is loaded.

Configure it explicitly in composer.json:

{
    "config": {
        "platform-check": true
    }
}

With this setting, Composer generates runtime checks for the supported PHP and extension requirements represented by its platform-check mechanism.

The platform-check configuration also supports "php-only" in Composer versions that provide this option. That setting limits the generated check to the PHP version rather than checking extensions.

For most applications, checking the required extensions is valuable because an extension can be present in the dependency metadata but absent from the actual runtime.

However, a generated platform check is not a replacement for deployment validation. It only checks the requirements covered by Composer's mechanism, and some problems may not become apparent until the application executes a particular code path.

Keep platform-check enabled unless there is a documented reason to change it.

Using Composer Commands in a Deployment Workflow

A reliable deployment process should validate dependency configuration, install the locked dependencies, and check the real runtime.

The following sequence provides a practical starting point:

composer validate --strict
composer install --no-dev --prefer-dist --optimize-autoloader
composer check-platform-reqs --no-dev

Each command serves a different purpose.

Run these commands in the appropriate deployment environment. If dependency installation happens in a build container but the application runs in a different production container, checking the build container alone is insufficient.

For reproducible deployments, commit composer.lock to version control for applications. The lock file records the resolved package versions, reducing the chance that different environments install different dependency versions.

Do not replace composer install with composer update during a routine production deployment. The update command resolves dependencies again and may change package versions.

Adding Platform Checks to CI/CD

You can run platform validation in a continuous integration pipeline before releasing an application.

For example, a simplified shell step could look like this:

set -e

composer validate --strict
composer install --no-interaction --prefer-dist
composer check-platform-reqs

The set -e statement causes the shell script to stop when a command fails, preventing later steps from continuing after a failed validation.

For a production deployment job, use the same PHP version and required extensions as the production runtime. If your CI environment intentionally includes development tools or additional extensions, consider adding a separate validation job that reproduces the production environment more closely.

This approach catches several problems before release:

• A dependency requires a newer PHP version than production provides.

• A required extension is missing.

• The Composer configuration is invalid.

• The lock file is inconsistent with the dependency declarations.

• The deployment environment differs from the environment used to resolve dependencies.

A successful platform check does not guarantee that every application feature works, so combine it with automated tests and appropriate integration tests.

Common Mistakes to Avoid

Advantages and Disadvantages

Composer platform configuration provides several benefits:

• It lets teams resolve dependencies against a defined PHP version.

• It reduces accidental dependency upgrades beyond the supported runtime.

• It helps identify missing PHP extensions before deployment.

• It supports more consistent dependency installation across environments.

• It integrates easily into CI/CD pipelines.

There are also limitations. Simulated platform configuration can create a false sense of security if the actual runtime is not checked. Extension availability may differ across containers and servers, and platform checks cannot replace application testing.

The best results come from combining a clearly defined target platform, a committed lock file, actual runtime validation, and automated tests.

Summary

Composer platform configuration helps PHP teams control which dependency versions are considered compatible with their target environment. Setting config.platform.php makes dependency resolution more predictable, but it does not install or emulate the actual runtime for application execution.

Use composer check-platform-reqs to verify the real PHP version and required extensions. Keep composer.lock under version control, run validation in CI/CD, and ensure that checks use an environment representative of production.

These practices help identify PHP version mismatches and missing extensions before deployment, reducing avoidable release failures.