Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

Composer says the root composer.json requires a PHP version your PHP does not satisfy

ErrorRoot composer.json requires php ^8.2 but your php version (8.1.2) does not satisfy that requirement.

Short answer

Composer compares the php constraint in your composer.json, or in a package, with the PHP that runs Composer. Read the full message to see which one fails. Then upgrade the PHP that Composer uses, correct a fake config.platform entry, or ignore the requirement only as a short test.

  • Applies to Composer 2, Laravel 12, PHP 8.3
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Ask Composer which PHP and extensions it sees, and who blocks a given PHP version.

    composer show --platform
    composer why-not php 8.3
  2. 2Match what you see, then jump to its fix

    1. 1The version in the message is lower than the one you installedThe PHP that runs Composer is older than the project needsFix
    2. 2composer show --platform shows a PHP version different from php -vconfig.platform in composer.json fakes an older PHPFix
    3. 3Only a one-off run is wanted, not a permanent changeYou need to test on a PHP you cannot change right nowFix

What does the error look like?

  • Root composer.json requires php ^8.2 but your php version (8.1.2) does not satisfy that requirement.
  • Your requirements could not be resolved to an installable set of packages.

Cause 1 of 3

The PHP that runs Composer is older than the project needs

1Check

Laravel 12 needs PHP 8.2 or newer. The command line may run an older PHP than the one you meant to use.

php -v
which -a php

2Fix

Install a supported PHP and make it the one on PATH, or call Composer with that binary explicitly.

php8.3 $(which composer) install

3Verify

composer install no longer prints the requirement error.

composer install

Confirmed by laravel.com

Did this fix it?

Cause 2 of 3

config.platform in composer.json fakes an older PHP

1Check

The platform option makes Composer resolve against a faked PHP and ignore the local one. An old value there keeps blocking newer packages.

grep -n -A4 '"platform"' composer.json

2Fix

Set it to the PHP of your real target server, or remove it, then update the lock file.

{
    "config": {
        "platform": { "php": "8.3.0" }
    }
}

3Verify

Run composer update and check that the lock file resolves.

composer update

Confirmed by getcomposer.org

Did this fix it?

Cause 3 of 3

You need to test on a PHP you cannot change right now

1Check

Composer can ignore one platform requirement for a single command. It warns this may hide real problems in production.

composer why-not php 8.3

2Fix

Ignore only the php requirement, and only for this run. Do not ship the result.

composer install --ignore-platform-req=php

3Verify

Run check-platform-reqs on the target server before deploying.

composer check-platform-reqs

Confirmed by getcomposer.org

Did this fix it?

How do I stop it coming back?

  • Pin config.platform.php to your production PHP so Composer resolves what the server can run.
  • Run composer check-platform-reqs in the deploy step.
  • Keep the PHP version the same on development, CI and production.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Back end

composer require maatwebsite/excel fails to install

Composer says the package needs an older PHP than the one installed

Composer refuses maatwebsite/excel when the PHP version or a PHP extension does not match what the package and PhpSpreadsheet need.

3 causes, each with a fix

Back end

composer require laravel/horizon fails: ext-pcntl is missing

laravel/horizon v1.1.0 requires ext-pcntl * -> the requested PHP extension pcntl is missing from your system

Horizon needs the pcntl extension, and Composer refuses to install it where PHP lacks that extension.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.