Laravel Composer sees wrong PHP Version
When running composer install on a legacy Laravel project, you might encounter an error stating that the package requires PHP >= 5.6.4 while your system shows a version like 7.1.10. This discrepancy often stems from a fundamental misunderstanding of how Composer determines the active PHP interpreter rather than a misconfiguration within composer.json.
The root cause is almost exclusively found in the .dist or vendor/composer/installed.json files, but more commonly, it lies in the environment where you are executing the command. If your system has multiple PHP versions installedâsuch as via Homebrew on macOS, Linux package managers, or Windows WSLâthe shell might be pointing to a different executable than the one Composer is invoking.
How Composer Determines PHP Version
Composer does not hardcode the PHP version into its logic; it queries the php binary currently present in your system's PATH environment variable. When you run php -v, your terminal outputs 7.1.10, confirming that this is the CLI tool associated with your current shell session. However, if an alias exists in your shell configuration (like .bashrc or .zshrc) or if a symlink points to an older PHP version globally, Composer might be inadvertently picking up a different executable depending on how it was invoked or if the environment variables differ between your interactive shell and the build process.
A frequent culprit is the use of phpenv (from the rbenv suite) or php-build. If you installed PHP 7.1 via Homebrew but your default php command still resolves to the system's built-in PHP 5.5, Composer will report the older version even if your terminal shows the new one. This happens because different shells or scripts might source different environment files.
Diagnosing the Discrepancy
To resolve this, you must ensure that the php command invoked by Composer matches the one you inspect manually. Run the following command to compare the paths:
which php
composer -V
If which php returns a path pointing to PHP 7.1 (e.g., /usr/local/bin/php) but the error message persists, check if there is an alias or function overriding the default behavior:
type -a php
If you see multiple entries, note that Composer might be using the first one listed in its internal environment detection, which could differ from your current shell's active path.
Fixing the Configuration
If you have PHP 5.6 installed globally (common in older tutorials or shared hosting setups), and your project expects it, ensure you are not accidentally invoking that version. However, since you need PHP 7.1 for modern compatibility, the goal is to align Composer's view with your actual system state.
In some cases, especially with Docker or CI/CD pipelines, the PATH might be set differently than in your local terminal. If you are using a tool like phpenv, ensure that the correct version is active before running composer:
phpenv global 7.1.10
composer install
Alternatively, if you have an alias in your shell configuration forcing PHP to point to an older version, remove or update it. For instance, on macOS with Homebrew, ensure that /usr/local/bin is prioritized over system directories like /usr/bin.
Why This Matters for Legacy Projects
Laravel 5.4, referenced in your composer.json, officially dropped support for PHP 5.6 in later minor versions and required PHP 7.0+. The requirement listed as >=5.6.4 is outdated if you are targeting modern PHP versions. If you encounter this error with a newer PHP version, it indicates that the lock file or composer metadata might be stale, or the project was originally designed for an older environment.
If you are upgrading from PHP 5 to 7, ensure that all dependencies in your composer.json are compatible with PHP 7.1. Some packages listed in your manifest (like spatie/laravel-permission) may have version constraints that conflict with newer PHP releases if not updated properly.
Final Steps
After ensuring the correct PHP binary is in your path, clear any cached data and reinstall dependencies:
composer clear-cache
composer install --no-dev
This ensures Composer re-evaluates the PHP version from scratch without relying on cached environment data. If the issue persists, inspect the composer diagnose output for additional clues regarding environment inconsistencies.
