How to Upgrade a Legacy PHP App to PHP 8.4/8.5 Without Breaking It
Old PHP versions are a security and hiring liability. Here is the low-risk, tool-assisted process we use to upgrade a legacy PHP app to PHP 8.4 or 8.5.
Running PHP 7.x or early 8.x in 2026 means no security fixes, slower performance and a shrinking pool of developers willing to work on the code. The good news: with the right tooling, upgrades are far less painful than they used to be.
Step 1: Get a safety net
Before touching code, add tests around the critical paths — even simple HTTP smoke tests that hit key pages and assert a 200 response are a huge improvement.
Step 2: Let static analysis find the problems
composer require --dev phpstan/phpstan rector/rector vendor/bin/phpstan analyse src --level=3
Start at a low level and raise it gradually. PHPStan surfaces undefined methods, wrong types and removed functions long before users do.
Step 3: Automate the boring changes with Rector
// rector.php
use Rector\Config\RectorConfig;
return RectorConfig::configure()
->withPaths([__DIR__ . '/src'])
->withPhpSets(php84: true);
vendor/bin/rector process --dry-run vendor/bin/rector process
Rector rewrites deprecated syntax — implicit nullable types, old constructors, removed functions — across thousands of files in seconds. Review the diff like any other pull request.
Step 4: Update dependencies
Run composer outdated, upgrade frameworks one major version at a time and replace abandoned packages.
Step 5: Run both versions side by side
Use CI to run tests on the old and new PHP versions until the switch, then deploy to a staging server running the new PHP before production.
Common gotchas
- Dynamic properties are deprecated — declare properties or use
#[AllowDynamicProperties]temporarily. - Implicitly nullable parameters (
string $x = null) are deprecated in 8.4 — use?string. - Stricter type juggling can change comparison results in old code.
Planning a legacy PHP app upgrade with the business
Upgrading a legacy PHP app is as much about planning as code. Agree these points with stakeholders before work starts:
- Why now. Unsupported PHP versions stop receiving security fixes, hosting providers retire them and developers become harder to hire. Put the risk in business terms.
- Scope. Upgrade first, improve later. Mixing new features into the upgrade makes problems harder to trace.
- Estimates. Run static analysis and automated tools such as Rector early — the size of the report is the best predictor of effort.
- Release strategy. Small, frequent releases are safer than one big switch. Keep the application running on both versions in CI until you are confident.
- Reporting. Share a simple weekly update: what was fixed, what is left and any risks found.
Handled this way, a legacy PHP app upgrade becomes a predictable project with no surprise downtime — and leaves you with tests and tooling that make every future upgrade easier.
We have modernised PHP applications from version 5 upwards. Tell us about yours.
