PHP Version Upgrade Checklist
debt(d7/e5/b3/t5)
Closest to 'only careful code review or runtime testing' (d7). Rector and PHPStan can flag some deprecations, but the checklist itself (staging test, OPcache clear, dep check) is a process not detectable by tools; detection_hints.automated is no.
Closest to 'touches multiple files / significant refactor in one component' (e5). The quick_fix lists a multi-step process (fix deprecations, check deps, run Rector, staging test) which typically touches many files across the app to resolve deprecations and incompatible APIs.
Closest to 'localised tax' (b3). The checklist is a periodic devops process applied at upgrade time; it doesn't shape day-to-day code but imposes ongoing maintenance discipline (fixing deprecations as they appear).
Closest to 'notable trap most devs eventually learn' (t5). Misconception that you can upgrade PHP directly is a well-known gotcha; OPcache not being cleared and Composer dep mismatches are documented surprises devs learn after being burned once.
TL;DR
Explanation
PHP upgrade checklist: (1) Check current version EOL at php.net/eol. (2) composer outdated — update dependencies for new PHP version. (3) Run PHPCompatibility PHPCS to find incompatible code. (4) Run Rector for automated migration. (5) Enable E_ALL in dev and fix all notices/warnings/deprecations on current version first. (6) Set up staging environment with new PHP version. (7) Run full test suite. (8) Run with new version in shadow/canary mode. (9) PHP-FPM: update pool config for new version. (10) Monitor error logs after deployment. OPcache: clear after upgrade. JIT: reconfigure if used. Extensions: verify all needed extensions are available in new version.
Common Misconception
Why It Matters
Common Mistakes
- Upgrading PHP without first fixing all deprecation warnings on the old version.
- Not checking Composer dependency compatibility before upgrading.
- Forgetting to clear OPcache after PHP version change.
Code Examples
# Dangerous: direct prod upgrade without testing:
sudo apt-get install php8.3-fpm
sudo service php8.0-fpm stop
sudo service php8.3-fpm start# Safe upgrade process:
# 1. Fix deprecations on current version:
php -d error_reporting=E_ALL -d display_errors=1 index.php
# 2. Check deps:
composer check-platform-reqs --php-version=8.3
# 3. Run Rector:
vendor/bin/rector process --dry-run
# 4. Test on staging with new PHP
# 5. Monitor for 24h, then prod rollout
# 6. Clear OPcache after deploy