"composer install" fails on the server? Fix PHP version and extension errors

1. "your php version does not satisfy that requirement"

In our test, composer install on the older server said:

Your lock file does not contain a compatible set of packages. Please run composer update.
  Problem 1
    - symfony/console is locked to version v8.1.11 and an update of this package was not requested.
    - symfony/console v8.1.11 requires php >=8.4.1 -> your php version (8.2.35) does not satisfy that requirement.

The lock file lists the exact versions you tested. Some of them need PHP 8.4, and the server has 8.2.

Don't follow the "Please run composer update" advice on the live server. That would pick different package versions than the ones you tested, right on your live site. You have two good choices:

• Move the server to the newer PHP (usually the right answer, because old PHP versions stop getting security fixes). See moving a site to a newer PHP version and which PHP versions still get security fixes.
• Or tell Composer on your computer which PHP the server has, so it only picks versions that work there. In composer.json:

  "config": {
      "platform": {
          "php": "8.2.35"
      }
  }

  In our test, that alone wasn't enough: composer update still said the packages need PHP 8.4, because composer.json asked for symfony/console: ^8.1, and every 8.1 version needs PHP 8.4. Allow an older major version too, and let Composer change the packages it depends on (-W):

  composer require -W "symfony/console:^7.3 || ^8.0"

  Composer then moved to symfony/console 7.4, which needs only PHP 8.2. Test the app, and commit the new lock file. Older versions may stop getting fixes sooner, so plan the PHP upgrade anyway.

To check a lock file before you deploy, run this on the server. In our test, it named the exact package and PHP version that failed:

composer check-platform-reqs

2. "Composer detected issues in your platform" on the website

If you copy the vendor folder from your computer (or a build server) instead of running composer install on the server, Composer can't stop you. Instead, the site stops. In our test, every page gave a 500 error with this text, shown to visitors:

Composer detected issues in your platform:

Your Composer dependencies require a PHP version ">= 8.4.1".

The Nginx error log had the same message as a PHP Fatal error. This check lives in vendor/composer/platform_check.php, and it's there to protect you: the packages were written for a newer PHP.

The fix is the same as in step 1: newer PHP on the server, or a lock file made for the server's PHP. Then run composer install on the server, or build vendor with the same PHP version the server has.

3. Don't hide it with --ignore-platform-reqs

Forums often suggest composer install --ignore-platform-reqs, or turning off the check with composer config platform-check false. We tried both. The install worked, and the page loaded, because Composer skipped the check. But nothing was fixed: the packages still need PHP 8.4. Code that uses newer PHP features can then fail later, on any page, and without a clear message. Use these options only if you know exactly why an extension check is wrong, never to get past a PHP version error.

4. "it is missing from your system": a PHP extension

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

The project needs an extension the server doesn't have. On Debian and Ubuntu, each one is a package named after the PHP version:

sudo apt install php8.2-gd php8.2-intl

Common ones are gd or imagick (images), intl, mbstring, xml, zip, curl, bcmath and mysql. After installing, reload PHP-FPM so the website gets it too: sudo systemctl reload php8.2-fpm.

5. Make sure Composer and the website use the same PHP

Composer runs with the php command in your terminal. The website runs with PHP-FPM. On a server with several PHP versions, they can be different. Then Composer is happy, and the site isn't. Compare:

php -v
ls /run/php/
sudo grep -Rn fastcgi_pass /etc/nginx/sites-enabled/

If the site uses php8.2-fpm.sock but php -v says 8.4, run Composer with the site's version:

php8.2 /usr/bin/composer install --no-dev

The same goes for extensions. Check the website's list with php-fpm8.2 -m, not php -m.

The safe way to install on a live server

cd /var/www/example.com
sudo -u deploy composer install --no-dev --no-interaction

• install, never update, on the live server. It installs exactly what's in the lock file.
• --no-dev leaves out test and debug tools.
• Run it as the user that owns the code, not as root. Composer runs scripts from your packages, and they shouldn't run as root.

For deploys with no downtime, see release folders. For keeping packages safe and up to date, see the Composer security guide.

Quick list

• your php version does not satisfy: newer PHP on the server, or set config.platform.php and update on your computer. Never composer update on the live server.
• Composer detected issues in your platform (500 page): vendor was built for a newer PHP. Same fix.
• --ignore-platform-reqs: hides the problem, doesn't fix it.
• missing from your system: apt install php8.x-name, then reload PHP-FPM.
• Works in Composer, not on the site: compare php -v with the FPM socket the site uses.
• Check first: composer check-platform-reqs.

Official sources

• Composer: install and check-platform-reqs
• Composer: config.platform and platform-check
• Composer: running as root

Next steps: make sure the server's PHP still gets security fixes with our PHP version guide, and check out deploying Laravel on your own server.

ServerNest is being built to show each site's PHP version and extensions, and to install the ones a project needs. Join early access to try it first.

← Back to the security blog