Composer 2: Platform Check

Composer v2 has a new feature that your server environment is checked at the run-time before the autoloader is even initialized. This is everything you should know about it

When you dump the Composer autoloader (or when it's done automatically during a package add/update/remove operation), Composer v2 now creates a new vendor/composer/platform_check.php file that immediately terminates rest of the application if the current server platform does not match the original environment it was created on.

If the platform you run the application does not meet these requirements, the application will exit with a message similar to this:

Composer detected issues in your platform: Your Composer dependencies require a PHP version ">= 7.3.0" and "< 7.4.0". You are running 7.4.5.

Further, if the platform is missing certain extension that are missing, the error message will be extended to show missing extensions as well:

Composer detected issues in your platform: Your Composer dependencies require a PHP version ">= 7.3.0" and "< 7.4.0". You are running 7.4.5. Your Composer dependencies require the following PHP extensions to be installed: pdo, xml

vendor/composer/platform_check.php file

A typical platform_check.php looks like this:

<?php

// platform_check.php @generated by Composer

$issues = array();

if (!(PHP_VERSION_ID >= 70400 && PHP_VERSION_ID < 90000)) {
    $issues[] = 'Your Composer dependencies require a PHP version ">= 7.4.0" and "< 9.0.0". You are running ' . PHP_VERSION  .  '.';
}

$missingExtensions = array();
extension_loaded('pdo') || $missingExtensions[] = 'pdo';

if ($missingExtensions) {
    $issues[] = 'Your Composer dependencies require the following PHP extensions to be installed: ' . implode(', ', $missingExtensions);
}

if ($issues) {
    echo 'Composer detected issues in your platform:' . "\n\n" . implode("\n", $issues);
    exit(104);
}

This file is generated by Composer every-time you dump the autoloader.

Configuration

This feature is enabled by default in Composer v2. You can disable it by setting Composer configuration platform-check to false:

Project or global composer.json file

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

CLI

Project-specific: composer config platform-check false
Global: composer global config platform-check false

check-platform-reqs command

Composer v1 and v2 come with composer check-platform-reqs command that exits with a non-zero status code if the current platform does not meet required dependencies. You can disable run-time platform requirements check and run composer check-platform-reqs in the target server (or bake it to your CI/CD pipeline) to to make sure the platform requirements are met, but without having to check it on every-time Composer autoloader is loaded.

Constraints

The new run-time platform check makes sure the platform requirements that your root composer.json and all other packages require are met.

The most restrictive bounds are selected. For example, the root composer.json file might require PHP versions 7.3 and 7.4, but if there is a package that requires PHP 7.4 or 8.0, the final platform-check will require PHP 7.4 which satisfies both of the PHP version requirements.

At the moment, the following constraints are not checked with run-time check:

• Processor architecture: php-64bit require directives will be ignored.
• Extension versions: If you have a require directive similar to ext-foo: ^x.y.z, the version is not checked. There is no unified way to check PHP extension versions, so this makes sense.
• config.platform directives in the composer.json do not have any effect either. These directives are only used when finding the correct versions on package update/install operations.

Further, none of the require-dev constraints make it to the platform_check.php file.

CLI vs Application run-time

Composer is run with PHP CLI, but you are likely creating applications that run on a different run-time such as php-fpm or Apache's mod_php.

platform_check.php file is generated purely from the version/extension constraints your composer.json and its packages require. This makes it possible to use Composer with one PHP version while the target server has a different PHP version as long as both your Composer run-time and server run-time fulfill the version/extension constraints.

This is the biggest advantage of the run-time platform_check.php file vs the composer check-platform-reqs command because the CLI version checks the CLI environment which might not be the same as server environment.

Composer Min Autoload

This is a shameless self-plug to a composer plugin: ayesh/composer-min-autoload.

composer-min-autoload is an opinionated plugin from Sparta that converts Composer autoloader to a minimal one. It inlines some of the code to the vendor/autoload.php file, and from version v0.0.2 and forward, it will remove and not use the platform_check.php file regardless of the composer.json settings.

After installing the plugin you can run composer dma to generate the minimal autoloader.