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
How do you upgrade an old PHP app to PHP 8 safely?
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.
Which tool does what
| 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.
Step 1: get a safety net, however thin
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');
}
Step 2: run CI on both versions
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.
# .github/workflows/ci.yml
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.
Step 3: let Rector do the boring part
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.
Step 4: fix what tools cannot
The PHP 8 changes that bit me most in real projects:
-
String-to-number comparisons.
0 == "abc"wastruein PHP 7 and isfalsein PHP 8. Search for loose comparisons against user input and status codes. -
Warnings that became errors. Undefined array keys and properties are louder, and many internal functions now throw
TypeErroronnullwhere they used to return quietly. -
Removed extensions.
mysql_*(gone since 7.0),mcrypt, and oldeach()usage need real replacements, not shims. -
Dynamic properties are deprecated in 8.2. Add the properties or
#[AllowDynamicProperties]deliberately. -
Dependencies. Upgrade Composer packages one at a time with
composer why-not php 8.3to see which package blocks you.
Step 5: roll out the runtime in stages
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.
Diagnostic checklist
- [ ] Characterization tests cover the money paths
- [ ] CI runs tests, PHPCompatibility and PHPStan on both old and target PHP
- [ ] Rector runs one module per PR, reviewed as a normal diff
- [ ] Loose comparisons against strings are audited
- [ ] Removed extensions (
mysql_*,mcrypt) are replaced - [ ] Composer dependencies are upgraded individually with
why-notchecks - [ ] Deprecation logging is on in staging and canary
- [ ] New runtime goes live behind a traffic split with a tested rollback
FAQ
Should I go straight from PHP 7.x to 8.3?
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.
How long does a typical upgrade take?
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.
Can Rector break my code?
Yes, occasionally, especially with dynamic code. That is why you review diffs in small batches and rely on the test matrix.
What about the old framework version?
Upgrade PHP first while staying on a framework version that supports both PHP versions, then upgrade the framework as a separate project.
Do I need Docker for the staged rollout?
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.
Is it safe to keep running PHP 7.4 if the server is behind a firewall?
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.
Follow & Connect
- Website: Loop Origin
- Watch on YouTube: Resume Boost AI ยท PixelValut ยท Daily AI News By Ali
- LinkedIn: Loop Origin
- X: Muhammad Ali Mughal (@AliMughal887)
- GitHub: Loop Origin (@LoopOrigin)

Top comments (0)