In almost every legacy PHP project Loop Origin takes on, the first question is the same: which PHP version is production on? The answer is often 7.2 or 7.4, sometimes 5.6, on a server nobody wants to touch. PHP 7.4 reached end of life in November 2022, and PHP 8.0 followed a year later, so these apps run without security fixes and block every modern package. The team knows it. The upgrade keeps getting postponed because it feels like one big risky jump.
It does not have to be one jump. With the strangler fig from Part 1 and clean module boundaries from Part 2, the version upgrade becomes a series of small, tested pull requests that each leave production working. This post is the playbook I use.
I wrote this with help from AI tools and checked the tooling details against the Rector, PHPStan and PHPCompatibility documentation and the official PHP migration guides. I am a Principal Software Engineer in Karachi with 9+ years maintaining Laravel and plain-PHP systems, and the numbers below come from real upgrades, not benchmarks.
📚 Series Navigation — Modernizing Legacy PHP Without a Rewrite
Part 1: Strangler Fig for Legacy PHP: Run Old and New Side by Side Part 2: Untangling Dependency Cycles in a Modular Laravel Monolith Part 3 (This Post): Upgrading Old PHP Versions Safely With Rector and CI Part 4: Replacing Legacy Auth & Sessions Without Logging Everyone Out Part 5: From FTP Deploys and Cron Scripts to a Real Pipeline Part 6: Decommissioning the Old App: Shadow Traffic, Flags & Final Cutover Related earlier posts: Zero-Downtime Database Migrations in Laravel & Node.js SaaS · Production Observability on a Budget
Direct answer: Add CI that runs your tests on both the current and target PHP versions, scan for incompatibilities with PHPCompatibility and PHPStan, let Rector apply the mechanical code changes in small batches, upgrade Composer dependencies one at a time, then roll the new runtime out to one server or container first, with a quick way back.
| Tool | What it finds or does | Changes code? | Where I run it |
|---|---|---|---|
| PHPCompatibility (PHP_CodeSniffer) | Removed functions, syntax and extensions for a target version | No | CI, first pass |
| PHPStan | Type errors, undefined methods, wrong argument counts | No | CI, every PR |
| Rector | Automated refactors: version sets, deprecated calls, typed properties | Yes | Locally, small batches |
| Test suite (PHPUnit / Pest) | Behaviour regressions | No | CI matrix on old + new PHP |
| Error logs on canary | Runtime deprecations you missed | No | Staged rollout |
None of these is enough alone. Static tools miss dynamic code (call_user_func, string class names, extract()), and tests rarely cover everything in a legacy app. Together they catch most of it.
If the app has no tests, I do not start by writing unit tests for everything. I write 20 to 40 HTTP-level characterization tests for the money paths: login, checkout or invoicing, the main reports, any import job. They record what the app returns today, so I know when an upgrade changes it.
public function test_invoice_pdf_still_renders(): void
{
$this->actingAs(User::factory()->create())
->get('/invoices/1042/pdf')
->assertOk()
->assertHeader('content-type', 'application/pdf');
}
The key idea: code must pass on the old version and the new one at the same time, so every PR can ship to the current production server.
jobs:
test:
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
php: ['7.4', '8.3']
steps:
- uses: actions/checkout@v4
- uses: shivammathur/setup-php@v2
with: { php-version: ${{ matrix.php }}, coverage: none }
- run: composer install --no-interaction --prefer-dist
- run: vendor/bin/phpcs -p --standard=PHPCompatibility --runtime-set testVersion 7.4-8.3 app/ legacy/
- run: vendor/bin/phpstan analyse --memory-limit=1G
- run: vendor/bin/phpunit
At first the 8.3 job fails. That is fine. Mark it allowed-to-fail, and the list of failures becomes your backlog.
Rector applies the mechanical changes: each() loops, curly-brace string offsets, create_function, implicit nullable parameters, and so on. Configure it to stay compatible with the old version first, then raise the target later.
// rector.php
use Rector\Config\RectorConfig;
use Rector\Set\ValueObject\LevelSetList;
return RectorConfig::configure()
->withPaths([__DIR__.'/app', __DIR__.'/legacy'])
->withSkip([__DIR__.'/legacy/vendor_copied'])
->withSets([LevelSetList::UP_TO_PHP_74]); // later: UP_TO_PHP_80, then UP_TO_PHP_83
vendor/bin/rector process legacy/Billing --dry-run # review the diff
vendor/bin/rector process legacy/Billing # apply one module at a time
I run Rector one directory per PR, using the module boundaries from Part 2. A 300-line diff gets reviewed properly; a 30,000-line diff gets rubber-stamped.
The PHP 8 changes that bit me most in real projects:
0 == "abc" was true in PHP 7 and is false in PHP 8. Search for loose comparisons against user input and status codes.TypeError on null where they used to return quietly.mysql_* (gone since 7.0), mcrypt, and old each() usage need real replacements, not shims.#[AllowDynamicProperties] deliberately.composer why-not php 8.3 to see which package blocks you.
With CI green on both versions, the server change is the smallest step. I build a new PHP 8.3 container or server next to the old one, route 5% of traffic to it, and watch error logs and latency for a day, then 50%, then 100%. Rolling back means pointing traffic back at the old pool. Keep the old pool for a week.
If you would rather not run this yourself, Loop Origin does exactly this kind of server setup and maintenance work, and the code side as part of our Laravel development service.
why-not checks
For the code, yes, as long as Rector and CI step through the sets in order. Running each intermediate version in production is usually not worth it.
It depends on size and tests. On the mid-sized apps we see, it is usually a few weeks of part-time work spread over small PRs, not a frozen big-bang sprint.
Yes, occasionally, especially with dynamic code. That is why you review diffs in small batches and rely on the test matrix.
Upgrade PHP first while staying on a framework version that supports both PHP versions, then upgrade the framework as a separate project.
No. A second server or PHP-FPM pool behind the same load balancer works. Containers just make the old and new runtimes easier to keep side by side.
It reduces exposure but does not remove it. Unpatched runtimes also block security updates in your dependencies, which is often the bigger risk.
Next in this series, Part 4 covers replacing legacy authentication and sessions without logging every user out.