upgrade-php

Upgrade PHP

When to use

• The user asks to upgrade PHP, or the project runs PHP 8.2 or older (see legacy/php-legacy).
• A dependency (Laravel 13 needs 8.3+) requires a newer PHP.

Before you start

• List every place that pins PHP: require.php and config.platform.php in composer.json, Dockerfiles (FROM php:…), CI (php-version:), hosting/PaaS settings, and PHPStan/Psalm phpVersion.
• List extensions in use (php -m, ext-* in composer.json) and check they exist for the target (PECL extensions lag).
• Working tree clean; new branch (chore/php-8.4).
• Ask the user:
  • the target: 8.4 (security support to Dec 2028) or 8.5 (to Dec 2029); default 8.4 for existing apps;
  • whether to stop for review after each minor hop;
  • whether network installs are approved (core/supply-chain cooldown applies).

Steps

1. Baseline on the current version: composer install, PHPStan, tests, and the app starting. Record failures. If PHPStan isn't set up, add it at a level the code passes and generate a baseline (vendor/bin/phpstan analyse --generate-baseline), so new errors stand out.

2. Surface deprecations on the current version: run the tests with error_reporting=E_ALL and deprecations converted to failures (PHPUnit failOnDeprecation="true" or convertDeprecationsToExceptions), and fix them first.

3. Add Rector (composer require --dev rector/rector) with a config that targets the next minor only:

   // rector.php
   use Rector\Config\RectorConfig;
   
   return RectorConfig::configure()
       ->withPaths([__DIR__ . '/src', __DIR__ . '/app', __DIR__ . '/tests'])
       ->withPhpSets(php83: true);   // the hop's target: php82, php83, php84, php85
   

   vendor/bin/rector process --dry-run
   vendor/bin/rector process
   

   Review the diff; Rector's PHP sets modernize syntax but don't fix every runtime change.

4. Hop one minor version: update require.php (for example "^8.3"), config.platform.php, Docker, CI and hosting together; run composer update --with-all-dependencies for packages that need newer versions (one package group at a time); install missing extensions.

5. Fix runtime changes from the PHP migration guide for that version (backward-incompatible changes and deprecations). Examples: 8.2 dynamic properties deprecated (#[\AllowDynamicProperties] only as a temporary bridge); 8.3 typed class constants and json_validate; 8.4 implicitly nullable parameter types deprecated (?Type $x = null), new Deprecated attribute; 8.5 removals listed in its migration guide.

6. Verify (next section), show the diff and results, and wait for approval before the next hop. Commit only when asked (git-commit skill).

7. At the target, raise the PHPStan level gradually as a separate change, and switch to languages/php.