How composer check php version?

How composer check php version?

  1. Blog
  2. 15 November 2026
  3. 3 min read

Stefan Bogdanescu

Founder & Senior Architect

How Composer Checks PHP Version Requirements

When you run composer require phpunit/phpunit, the tool immediately validates your environment against a set of constraints defined in the package's metadata. If the output reports an error stating that your PHP version or config.platform.php value does not satisfy a requirement, it is because Composer is actively verifying these conditions before attempting to install anything. This behavior prevents you from installing packages that will inevitably fail at runtime due to missing extensions or unsupported language features.

The core mechanism driving this validation is the platform configuration. When Composer initializes, it scans your system for specific environment variables and executable paths. By default, it looks for the PHP_VERSION environment variable. If that variable is absent, Composer falls back to executing the php -v command on your current shell path. In your specific scenario, running which php reveals that your terminal is invoking the binary located at /Applications/MAMP/bin/php/php5.6.10/bin/php. This executable reports itself as PHP 5.6.10.

However, the error message indicates a discrepancy between what Composer sees and what you expect. The message explicitly mentions two potential sources for the version check: your actual PHP process or the config.platform.php value. It is crucial to understand that Composer does not rely solely on the version string printed by php -v. It also checks the platform.php entry within its global configuration file, typically located at ~/.composer/config.json.

If you have manually set a specific version in your config, say "config.platform.php": "5.6", Composer will use that static string for requirement checks regardless of what version the binary actually reports. This is a common source of confusion when switching between different PHP versions on the same machine, such as using MAMP or Homebrew alongside system PHP. If your config.json lists "platform.php": "5.5.27", Composer will reject any package requiring 5.6 even if your current binary is 5.6.10. This design allows developers to simulate environments or define project constraints without changing their local shell aliases, but it can lead to unexpected failures if the configuration is not aligned with reality.

To resolve an error like your PHP version (5.5.27) ... does not satisfy that requirement when your actual binary is 5.6.10, you must first verify whether a stale configuration value exists. You can inspect this by running:

composer config --global platform.php

If this command outputs 5.5.27, you need to remove or update that entry in your ~/.composer/config.json file to reflect the true version of PHP you are using. Once the configuration matches the reality of your execution environment, Composer will correctly validate requirements against the active binary.

The Role of Platform Constraints in Deployment

This validation logic is not merely a safety net for local development; it is a critical part of the deployment lifecycle. When you commit a composer.json file to version control, the require section defines the strict PHP version needed by your dependencies. For instance, PHPUnit 5.0.4 explicitly requires PHP >= 5.6. If you attempt to deploy this project to a server running PHP 5.5, Composer will refuse to install the package unless you use the --ignore-platform-reqs flag.

While ignoring platform requirements can bypass installation errors, it is generally an anti-pattern because it masks compatibility issues that will cause your application to crash later. The tool's insistence on checking these versions ensures that the runtime environment matches the build-time expectations of your dependencies.

Understanding how Composer resolves these conflicts—prioritizing actual binaries when no config override exists, and respecting explicit config overrides—is essential for managing multi-PHP environments. Whether you are switching between PHP 7.x and PHP 8.x on a single machine or preparing a project for production, ensuring the platform.php configuration aligns with your active PHP installation is the key to avoiding these friction points.

Our network