Ryz Labs/Migrations/Legacy PHP to modern PHP
Migrations

Legacy PHP 5/7 to Modern PHP 8: Migration Runbook

How to get an old PHP codebase onto a supported PHP 8 release and a modern framework, route by route, without a big-bang rewrite or a dead weekend.

A legacy PHP 5 or 7 application gets to a supported PHP 8 release and a modern framework such as Laravel or Symfony through two tracks run in parallel. First, Rector and a static analyzer drag the old code onto a supported runtime. Second, a reverse proxy routes URLs one at a time to a new framework app that shares the old app's sessions. What decides success is the shared session and authentication layer: once users can move between old and new pages without noticing, every other route is just more work.

Why teams migrate now

Every PHP 7 release is now past end of life. php.net's unsupported branches list shows PHP 7.4 ending on 28 November 2022, 8.0 on 26 November 2023 and 8.1 on 31 December 2025. The supported versions page describes the cycle as two years of active support followed by two years of security fixes. As of today it shows:

So if you migrate to 8.2 now, you will be out of support again in January. Target 8.4 or 8.5, then move to 8.6 once your framework and extensions support it.

A PHP 5 app has the bigger problem. It usually also lacks Composer, prepared statements and output escaping, and it often has authentication written by hand. Unsupported PHP gets flagged in every PCI or SOC 2 review and in every scan a customer's security team runs. Distro packages and hosting control panels drop old runtimes, so you end up running a custom-compiled interpreter that nobody wants to own. And engineers who know Laravel or Symfony won't take a job editing include files that are 3,000 lines long.

Before you start: inventory and baseline

The strangler-fig plan, phase by phase

Phase 0: Composer and a safety net

Add a composer.json to the legacy app even if all it does at first is autoload. Map the existing class directories with a classmap autoloader, and use PSR-4 for any new code. Move vendored libraries into Composer where versions exist. Put the app in a container that matches production's PHP version exactly, so every developer and CI job runs the same interpreter.

Done when: composer install builds the app, the characterization suite runs in CI against the container, and the error-log baseline is recorded.

Phase 1: Static analysis baselines

Run PHPStan (or Psalm, or both) at a low level, then generate a baseline: phpstan-baseline.neon for PHPStan, or psalm-baseline.xml from psalm --set-baseline. The baseline records every existing error so CI can fail only on new ones. Then raise the level one step at a time and shrink the baseline file over time. Add PHP_CodeSniffer with the PHPCompatibility standard, configured for your target version, to list the calls that will not run there.

Done when: analysis runs on every PR, nothing new is added to the baseline, and the compatibility report is triaged into tickets.

Phase 2: Rector up to a supported runtime

Rector describes itself as a tool for instant upgrades and automated refactoring, and it covers upgrades from PHP 5.3 to 8.5. Configure rector.php with the PHP level sets for your path and run one set per pull request, not everything at once. Review each diff, run the characterization suite, and merge. Step the container's PHP version up as the code allows, running CI on the current and next versions side by side. Some changes need a person, not Rector:

Sequence the runtime path so you don't stop on a branch that is about to expire. 8.2 runs out on 31 December 2026, so treat it as a stepping stone at most.

Done when: the legacy app runs in production on PHP 8.4 or later, the error log is at or below baseline, and there are no mysql_* calls left.

Phase 3: Front controller, proxy and the new app

Stand up the new Laravel or Symfony application on the same PHP version. Put nginx, or your load balancer's path rules, in front of both apps. Every URL goes to the legacy app by default. Each migrated route gets a location block, or a path rule, that sends it to the new app's public/index.php. Inside the new app, a fallback route can also hand unknown paths back to the legacy code: Route::fallback in Laravel, or a catch-all controller in Symfony that includes the legacy script. Either way, users see one site and one domain.

Share sessions explicitly. The simplest path is to point both apps at the same session store, Redis or the database, with the same cookie name and domain, and to have the new app read the legacy session format. Symfony's PhpBridgeSessionStorage exists to work alongside a session the legacy code already started with session_start. In Laravel, write middleware that reads the native session and logs the user into the guard. Move password hashes to password_hash on the user's next login, using password_verify and password_needs_rehash, so old md5 hashes drop out without a forced reset.

Done when: a logged-in user can move between legacy and new pages with no second login, the first low-risk route is served by the new app, and logout clears both apps.

Phase 4: Route by route

Migrate in order of risk and value. Start with read-only pages, then forms, then checkout and account management. Each route is rebuilt with the framework's validation, Eloquent or Doctrine against the existing schema (don't redesign tables in the same step), and Blade or Twig templates, which escape output by default. For each route, run the characterization tests against both implementations before you flip the proxy rule. Move cron scripts to the Laravel scheduler or Symfony Messenger workers one at a time.

A route is done when characterization tests pass on the new app, error rate and p95 match baseline after the switch, and the legacy file is deleted, not just bypassed.

Phase 5: Retire the legacy tree

When the access logs show no traffic left on the legacy paths, remove the fallback route and the legacy session bridge, and normalize what you deferred: character sets to utf8mb4, schema cleanup through framework migrations, and the PHPStan level raised to where your team wants it.

Done when: one application, one front controller, a supported PHP version, an empty baseline or one shrinking on a schedule, and a plan for moving to the next PHP minor.

PhaseGoalKey techniqueExit criteria
0. Composer and testsReproducible buildcomposer.json classmap, pinned container, HTTP characterization testsSuite runs in CI on the production PHP version
1. BaselinesStop new debtPHPStan or Psalm baseline, PHPCompatibility sniffNo new baseline entries on PRs
2. Runtime upgradeLegacy code on supported PHPRector level sets one PR at a time, mysql_* to PDOProduction on 8.4+, error log at baseline
3. Proxy and bridgeTwo apps, one sitenginx path routing, shared session store, password rehashNo second login across apps
4. Route by routeMove behavior to the frameworkRebuild per route on the existing schema, dual test runsLegacy file deleted per route
5. RetireOne codebaseRemove fallback and bridge, fix charsetsNo legacy traffic in logs

Cutover and rollback

Traffic moves by path at the proxy. For a route that matters, switch first by cookie or header: an internal staff cookie sends staff to the new app while everyone else stays on legacy. Then move a percentage of traffic using nginx split_clients or weighted target groups, and finally send all of it. For read endpoints, mirror requests to the new app (nginx's mirror directive works) and diff the rendered output, with CSRF tokens and timestamps stripped. For writes, both apps write to the same database, so there is no dual-write problem. The risk is the two apps disagreeing about validation or derived columns, and that is what the characterization tests must cover.

Before any route flips, confirm:

How each stage reverses. A runtime upgrade from Phase 2 reverses by redeploying the previous container image with the older PHP, which works because Rector pull requests are kept compatible with both versions until the old version is retired. In Phases 3 and 4, a route rolls back by deleting its proxy rule and reloading nginx. The legacy file is still there until the route has been stable long enough for you to trust it, which is why deleting it is the last step and not the first. A session bridge failure rolls back by sending the migrated routes back to legacy together, never one by one. In Phase 5 there is no fast rollback, so don't start it until the legacy paths have been silent in the logs for a full business cycle, including month-end jobs.

Risk matrix

RiskLikelihoodImpactMitigationEarly warning signal
Session bridge drops users between appsMediumHighShared store, same cookie name and domain, staff-cookie trial firstLogin rate rises on routes just moved
Character set double-encodingHighMediumMatch the legacy connection charset in the new app, convert data only in Phase 5Mojibake in names or addresses on new pages
Rector change alters behaviorMediumMediumOne rule set per PR, characterization suite, human diff reviewGolden-file test diff on exports
Hidden entry points missedHighMediumAccess-log inventory, a default-to-legacy proxy rule404s or 5xx on paths no one listed
Encoded files or abandoned extensions block the runtime upgradeMediumHighInventory php -m and encoded files first, rebuild those modules earlyContainer fails to start on the next PHP
SQL injection uncovered during the PDO rewriteHighHighTreat as security tickets, patch on legacy immediately, don't wait for the route moveStatic analysis taint warnings, WAF hits
Weak password hashes lingerMediumHighRehash on login, force a reset for dormant accounts laterShare of md5 hashes not falling
Cron jobs run twice or not at all during the moveMediumMediumMove one job at a time, lock with a database or cache mutexDuplicate emails or missing nightly files
Landing on PHP 8.2 and expiring at year endMediumMediumTarget 8.4 or 8.5 as the first production stopPlan or tickets naming 8.2 as the end state

Typical team shape

Who does the work:

Many teams begin with a pod of 3 to 5 senior engineers (a tech lead plus engineers), and a full pod is about seven. Ryz engineers on your team start from $7,000 per month (our published range is $7,000–$15,000 per engineer per month, mostly mid-level to senior), quoted per team. Ryz engineers work on your team, reporting to your leads. To estimate the work, multiply team size by months by the monthly rate. The number of entry points and how many raw queries the code has decide the months. See PHP developers, Laravel developers and PHP developer rates, or scope your team.

Where an AI pod helps (and where it doesn't)

Our AI pod uses coding assistants for the work that is high-volume and easy to check. That includes drafting HTTP characterization tests from access-log samples, turning concatenated mysql_* queries into PDO calls with bound parameters, sorting a large PHPStan baseline into fix-now and fix-later groups, drafting first versions of Blade or Twig templates from legacy HTML, and summarizing shadow-diff output. Rector stays the main tool for runtime upgrades because its rules are deterministic, and AI-drafted code fills the gaps Rector has no rule for.

It doesn't make the decisions. Route order, the session bridge design and anything that touches authentication are decided by senior engineers. Every generated change goes through human review, the static analysis gate and the characterization suite before it merges, and an engineer reads every security-relevant diff line by line.

When not to migrate (yet)

We're not the right fit if you want a self-serve marketplace of hourly freelancers for a quick patch job.

Related

FAQ

How long does a PHP 5 to PHP 8 migration take?

It depends on the number of public entry points, how much SQL is built from raw request input, whether Composer and tests exist already, which extensions or encoded files block newer runtimes, and whether you are also moving to a framework or only upgrading the runtime. The access-log inventory and the first static analysis baseline tell you the real size.

Can the old and new PHP apps run at the same time?

Yes, and they should. A reverse proxy sends each URL to either the legacy app or the new Laravel or Symfony app, both read the same database and session store, and users see one site. Routes move one at a time, and each can be moved back by removing one proxy rule.

Should we pick Laravel or Symfony?

Both are mature and both work for a strangler migration. Laravel tends to suit teams that want convention and fast scaffolding. Symfony suits teams that want explicit configuration and reusable components, and its session bridge for legacy code is a practical advantage. Pick the one your team will maintain, then stick with it.

Do we have to freeze features while we migrate?

No. New features go into the new framework app from day one, behind a proxy rule, and bug fixes still land in legacy until a route moves. The one thing to freeze is schema redesign until the routes that touch those tables have moved.

What will a PHP modernization cost?

Multiply the number of engineers by the months of work by the monthly rate per engineer. The team size depends on how many routes can move in parallel. The months depend on the entry-point count, the amount of raw SQL and how much test backfill is needed before the first route can safely move.

Questions we didn't answer? Email info@ryzlabs.com.

Thanks — your message has been sent. We’ll get back to you soon.

Something went wrong while sending your message. Please try again or email info@ryzlabs.com.

Explore Ryz Labs

Software development servicesAI development companyIndustriesStaff augmentationAI pod teamsNearshore software developmentHire engineers by roleEngineer ratesGuidesBuyer guidesCase studiesHow we vet engineers

Ryz Labs

Senior engineers on your team. AI pod teams that ship.

Tell us what you're building. You get a scoped plan, a price and the names of the people who would do the work.

  • Only the top 1% of tens of thousands interviewed make it
  • On US business hours, including New York hours
  • Trusted by Fortune 500 engineering teams

Tell us who you need

A Ryz partner replies with a scoped team plan.

Start a conversation →

Prefer to talk? Book a 15-min call →