Writing / Problems solved

Migrating a high-traffic PHP application to 8.4

A controlled PHP 7.3-to-8.4 migration using Cloudflare Load Balancer canaries, two origin pools, explicit compatibility checks, and a rollback that's just a traffic switch.

One of the calmer production migrations I've done was also one of the highest-risk on paper: moving a legacy PHP application from 7.3 to 8.4 while it served roughly 100,000 daily active users.

I couldn't pause the application while I found compatibility issues. A one-shot cutover would have turned every unknown into a production incident. A rewrite would have blown up the change surface and delayed the runtime upgrade for months.

So the plan optimized for one thing: reversibility. Keep the existing traffic-control layer, run both runtimes in parallel, shift traffic gradually, and make rollback a routing change instead of a new deployment.

The migration unit was traffic, not code

The application ran behind Cloudflare Load Balancer. I set up two origin pools:

  • the stable pool kept the PHP 7.3 application nodes
  • the candidate pool ran the PHP 8.4 application nodes

The load balancer gave me a weighted split. The rollout started at 95% of traffic on PHP 7.3 and 5% on PHP 8.4. The candidate pool grew — more nodes, more traffic — only after production behavior held up.

flowchart LR
  Users["Production traffic"] --> LB["Cloudflare Load Balancer"]
  LB -->|95% initially| Stable["PHP 7.3 pool"]
  LB -->|5% initially| Candidate["PHP 8.4 pool"]
  Stable --> App["Application and dependencies"]
  Candidate --> App

That arrangement made rollback intentionally boring:

disable PHP 8.4 pool
send traffic to PHP 7.3 pool
inspect failure and compatibility issue
deploy fix to PHP 8.4 pool
resume canary

Nobody had to reverse a database migration or restore an image. They changed the traffic weights.

Why staging wasn't enough

The compatibility failures that scared me weren't syntax errors. A legacy application carries assumptions about runtime behavior across a long tail of code paths:

  • warnings that become exceptions or change severity
  • weak typing exposed by particular user inputs
  • dependency behavior staging never exercises
  • framework and library edges under the newer runtime
  • scheduled jobs and admin flows with uneven traffic
  • routes whose production data shape differs from test fixtures

Staging catches the obvious failures. It's not proof that every production path is compatible. I'd rather let reality tell me what's wrong than trust staging to have covered it — so I designed the rollout around that uncertainty instead of pretending I could eliminate it before real traffic was involved.

What the canary actually tested

The canary wasn't just a health check. It ran the application under real request distribution and real data shape. The signals that mattered:

Signal

Why it mattered

HTTP error rate

Detects requests that fail at the boundary.

Application logs

Identifies runtime and dependency failures.

Route-level behavior

Keeps a healthy median from hiding one broken endpoint.

Background jobs

Covers work request traffic doesn't exercise.

Resource saturation

Detects runtime or configuration regressions.

Business-level symptoms

Finds failures that return technically valid responses.

The traffic split was a risk-control mechanism, not an observability substitute. A small canary only helps if you can tell why a candidate request failed and whether the failure is isolated or systemic.

Failure handling was part of the design

If a route failed on PHP 8.4 but worked on PHP 7.3, the response was decided in advance: disable the candidate pool, return traffic to the stable pool, isolate the issue, deploy the fix, re-enable the canary.

That's different from “we can roll back if we need to.” A real rollback plan specifies:

  • the operator and permission required
  • the exact control-plane action
  • the observable condition that triggers rollback
  • the state that does and doesn't need reverting
  • the verification required before traffic resumes

Rollback is safest when it's a normal, rehearsed operation — not a heroic move invented mid-incident.

Why not build a migration platform?

The load balancer already expressed exactly the control I needed: route a percentage of requests to one pool and the rest to another. A custom migration service would have added a second traffic-control plane, a second operational interface, and another failure mode.

The existing architecture was enough because the migration boundary was the runtime pool. It didn't need request-level session pinning, a data rewrite, or a new orchestration system. The right migration abstraction is the smallest one that makes the change reversible. More machinery isn't more safety when it puts untested machinery on the critical path.

The outcome

The migration moved in small, production-proven steps instead of one high-pressure cutover. The result I cared about wasn't only that PHP 8.4 ran fine — it was that compatibility failures could be isolated to the candidate pool without taking the application down with them.

For high-traffic runtime migrations, the hard part isn't installing the new version. It's building a path where real traffic can teach you what's broken while the old version stays one traffic-weight away.

PHP 8.6 was released on 19 November 2026, the same day as security releases for 8.2 through 8.5, and security support for PHP 8.2 ends on 31 December 2026; the dates are in PHP 8.6 is out, and PHP 8.2 security support ends on 31 December.

Bhavin Kamani

A small command line for a curious visitor.