Introduction

Composer checks that the runtime environment meets the platform requirements declared by dependencies. When a package requires php >= 8.1 but the system runs PHP 8.0, or a required extension is missing, composer install fails. This commonly happens when deploying to servers with older PHP versions than development machines, or when upgrading packages that bump their minimum PHP requirement.

Symptoms

  • Your requirements could not be resolved to an installable set of packages.
  • Problem 1 - Root composer.json requires php ^8.1 but your php version (8.0.30) does not satisfy that requirement.
  • Problem 2 - package/name 2.0.0 requires ext-gd * -> it is missing from your system.
  • Works on developer machine but fails on production server
  • composer update succeeds locally but composer install fails on CI/CD

``` Loading composer repositories with package information Updating dependencies Your requirements could not be resolved to an installable set of packages.

Problem 1 - Root composer.json requires PHP extension ext-redis * but it is missing from your system. Install or enable PHP's redis extension.

Problem 2 - laravel/framework[v10.0.0, ..., v10.48.0] require php ^8.1 -> your php version (8.0.30) does not satisfy that requirement. ```

Common Causes

  • Production server running older PHP than development machine
  • Package upgraded to version requiring newer PHP
  • Missing PHP extensions (gd, intl, redis, zip, etc.)
  • composer.lock generated on newer PHP, deployed to older PHP
  • Docker base image with outdated PHP version

Step-by-Step Fix

  1. 1.Check PHP version and extensions:
  2. 2.```bash
  3. 3.# Check PHP version
  4. 4.php -v
  5. 5.# PHP 8.0.30 (cli)

# Check required extensions php -m | grep -E "gd|redis|intl|zip|mbstring|xml"

# Check Composer platform requirements composer check-platform-reqs

# Show which packages need which PHP version composer why-not php 8.1 ```

  1. 1.Upgrade PHP on the server:
  2. 2.```bash
  3. 3.# Ubuntu/Debian
  4. 4.sudo add-apt-repository ppa:ondrej/php
  5. 5.sudo apt update
  6. 6.sudo apt install php8.2 php8.2-fpm php8.2-cli php8.2-mbstring php8.2-xml php8.2-gd php8.2-redis

# Switch CLI default sudo update-alternatives --set php /usr/bin/php8.2

# Verify php -v # PHP 8.2.x ```

  1. 1.Configure Composer platform check:
  2. 2.```json
  3. 3.// composer.json - specify the target PHP version
  4. 4.{
  5. 5."config": {
  6. 6."platform": {
  7. 7."php": "8.1"
  8. 8.}
  9. 9.}
  10. 10.}

// This tells Composer to resolve dependencies for PHP 8.1 // even if running on PHP 8.2 // Useful for generating lock files for older production servers ```

  1. 1.Use --ignore-platform-reqs (temporary workaround):
  2. 2.```bash
  3. 3.# Ignore PHP version check (risky - may cause runtime errors)
  4. 4.composer install --ignore-platform-req=php

# Ignore specific extension composer install --ignore-platform-req=ext-redis

# Ignore ALL platform requirements (NOT RECOMMENDED) composer install --ignore-platform-reqs

# WARNING: This may install packages that will fail at runtime # Only use when you are certain the code is compatible ```

  1. 1.Fix Docker PHP version:
  2. 2.```dockerfile
  3. 3.# WRONG - outdated PHP version
  4. 4.FROM php:8.0-fpm

# CORRECT - match production requirements FROM php:8.2-fpm

RUN docker-php-ext-install pdo_mysql mbstring xml gd intl

# Verify in build RUN php -v && php -m ```

Prevention

  • Pin PHP version requirement in composer.json:
  • ```json
  • {
  • "require": {
  • "php": "^8.1"
  • }
  • }
  • `
  • Use composer check-platform-reqs in CI pipeline
  • Match production PHP version in development with config.platform.php
  • Use Docker with consistent PHP versions across all environments
  • Test package upgrades in staging before production deployment
  • Monitor PHP version end-of-life dates and plan upgrades accordingly
  • Use composer platform-check plugin to verify at runtime