PHP Upgrade

PHP Version Upgrade

Upgrade one minor version at a time. Never skip versions - each step surfaces deprecations that become errors in the next release. Every upgrade follows the same cycle: audit, automate, test, deploy.

Core Principles

Upgrade Process Overview

Phase 0: Read the Changelog

Before touching any code, obtain the actual changelog for the target PHP version:

1. Search the web for PHP X.Y migration guide (e.g., PHP 8.4 migration guide php.net)
2. Or ask the user to provide the changelog / release notes
3. Read the official migration page at https://www.php.net/manual/en/migrationXY.php

This is non-negotiable. Each version has unique changes that static skill knowledge cannot fully capture.

Phase 1: Audit

Before changing any code, understand the scope of the upgrade.

1. Run PHPCompatibility against the target version to identify incompatible code
2. Run php-parallel-lint with the target PHP binary to catch syntax errors
3. Run composer outdated to check if all dependencies support the target version
4. Review the official migration guide at php.net for the target version
5. Check PHP extensions for compatibility (ext-intl, ext-mbstring, etc.)

Phase 2: Automate

Use Rector to handle the bulk of code transformations automatically.

// rector.php
use Rector\Config\RectorConfig;

return RectorConfig::configure()
    ->withPaths([__DIR__ . '/src', __DIR__ . '/tests'])
    ->withPhpSets(php84: true);  // adjust to target version

Always dry-run first:

vendor/bin/rector process --dry-run

Review changes, then apply:

vendor/bin/rector process

Commit Rector changes separately from manual fixes for clean git history.

Phase 3: Update Dependencies

1. Update composer.json with the new PHP version constraint: "php": ">=8.4"
2. Update config.platform.php to match the target version
3. Run composer update and resolve conflicts
4. Update PHP extensions as needed

Phase 4: Test and Deploy

1. Run the full test suite under the new PHP version
2. Run static analysis (PHPStan/Psalm)
3. Deploy to staging and verify
4. Monitor production logs for deprecation notices after deployment

See Upgrade Process Reference for detailed tool configuration, CI pipeline setup, and Docker considerations.

Tools

Breaking Changes by Version

See Version Changes Reference for complete per-version details with code examples.

Common Pitfalls

Quick Reference: Upgrade Checklist

• Review php.net migration guide for target version
• Run PHPCompatibility scan against target version
• Run php-parallel-lint with target PHP binary
• Verify all Composer dependencies support target version
• Configure and run Rector with target version set (dry-run first)
• Review and commit Rector changes
• Apply manual fixes for remaining issues
• Update composer.json PHP constraint and config.platform.php
• Run composer update
• Run full test suite on target PHP version
• Run static analysis (PHPStan/Psalm)
• Deploy to staging and verify
• Deploy to production and monitor logs

Reference Files

Integration with Other Skills