Quick answer: Decommission a legacy PHP app in four stages: measure which routes still get traffic, mirror real requests to the new code and diff the responses, move each remaining route behind a percentage feature flag, then cut over with a read-only period and a rollback window. Only delete servers, cron jobs and DNS after logs show zero legacy traffic for weeks.
This is the finale of the series. In Part 1 we put a Laravel app in front of the legacy code with the strangler fig pattern. Parts 2 to 5 untangled modules, upgraded PHP, moved auth and sessions, and replaced FTP deploys with a pipeline. At this point most traffic already goes to the new code, and that is exactly where many projects stall. The old app keeps running "just in case", and two years later you are still patching a PHP 7.2 server because one admin report lives there.
I'm Muhammad Ali Mughal, a Principal Software Engineer in Karachi, and at Loop Origin we take inherited apps through this last mile regularly. I wrote this with help from AI tools and checked the configuration against the Nginx, Laravel Pennant and Laravel documentation.
📚 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: 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 (This Post, Finale): Decommissioning the Old App: Shadow Traffic, Flags & Final Cutover
Related earlier post: Config & Feature Flags That Quietly Diverged Across Environments
Stage 1: find out what still hits the old app
You cannot turn off what you cannot see. Start by logging every request the proxy still sends to the legacy upstream, with a tag you can count.
log_format upstream_tag '$time_iso8601 $request_method $uri $status $upstream_addr route=$route_owner'; map $uri $route_owner { default legacy; ~^/api/ new; ~^/account/ new; ~^/admin/reports/ legacy; } server { access_log /var/log/nginx/routing.log upstream_tag; location / { if ($route_owner = new) { proxy_pass http://laravel_app; break; } proxy_pass http://legacy_app; } } ~~~{% endraw %} After a week, count legacy hits by path:{% raw %} ~~~bash grep 'route=legacy' /var/log/nginx/routing.log \ | awk '{print $3}' | sed -E 's/[0-9]+/:id/g' | sort | uniq -c | sort -rn | head -30 ~~~{% endraw %} This list is usually shorter and weirder than expected: a CSV export one finance user runs on Mondays, a webhook endpoint a partner still calls, a cron-triggered URL, image paths hard-coded in old emails. Each line becomes a ticket: migrate, redirect, or deliberately retire. Do not forget traffic that never passes through Nginx: cron jobs on the legacy box (Part 5 moved most of them), direct database writers, and other servers calling the legacy host by IP. ## Stage 2: shadow traffic to prove parity For routes that matter, such as reports, pricing or anything that returns numbers, I mirror real requests to the new implementation and compare the results before switching. Nginx's {% raw %}`mirror` module sends a copy of each request and discards the mirror's response, so users only ever see the legacy answer.{% raw %} ~~~nginx location /admin/reports/ { mirror /_shadow; mirror_request_body on; proxy_pass http://legacy_app; } location = /_shadow { internal; proxy_set_header X-Shadow-Request 1; proxy_pass http://laravel_app$request_uri; } ~~~{% endraw %} Two rules keep this safe: 1. **Only mirror reads.** A mirrored POST runs twice. In the new app, reject or no-op any shadow request that would write, and never send emails, charges or webhooks from it. 2. **Compare in the new app, not by eye.** The new app can call the legacy endpoint (or read a cached legacy response) and log differences.{% raw %} ~~~php // app/Http/Middleware/ShadowCompare.php (new app) public function handle(Request $request, Closure $next) { $response = $next($request); if ($request->header('X-Shadow-Request')) { abort_unless($request->isMethodSafe(), 405); $legacy = Http::timeout(5)->get(config('legacy.url').$request->getRequestUri()); $same = $this->normalise($legacy->body()) === $this->normalise($response->getContent()); Log::channel('shadow')->info('shadow-compare', [ 'path' => $request->path(), 'same' => $same, 'legacy_status' => $legacy->status(), 'new_status' => $response->getStatusCode(), ]); } return $response; } ~~~{% endraw %} {% raw %}`normalise()`{% endraw %} strips timestamps, CSRF tokens and whitespace so you compare data, not markup noise. When a route shows matching results for a week of real traffic, including month-end if it is a finance report, it is ready. ## Stage 3: flags for the last routes Switching proxy rules per route is fine for large chunks. For the last risky pieces I prefer a feature flag inside the new app, so I can move a percentage of users, or one internal team first, and roll back without a deploy. With Laravel Pennant:{% raw %} ~~~php // AppServiceProvider::boot() Feature::define('reports-v2', fn (User $user) => match (true) { $user->isInternal() => true, default => Lottery::odds(1, 10), // 10% of other users }); // Route Route::get('/admin/reports/{report}', function (Report $report) { return Feature::active('reports-v2') ? app(ReportController::class)->show($report) : redirect()->away(config('legacy.url')."/admin/reports/{$report->id}"); }); ~~~{% endraw %} Pennant stores the result per user, so a user does not flip between old and new on every request. Raise the percentage in steps (10, 50, 100) and watch error rates and support tickets between each. ## Stage 4: the cutover | Step | Duration | Done when | Rollback | |---|---|---|---| | Announce and freeze legacy changes | 1 week before | No more deploys to legacy | n/a | | Set legacy app read-only | 1–3 days | Legacy write attempts logged at zero | Remove read-only flag | | Point all routes to the new app | Minutes | Routing log shows no "legacy" tags | Restore previous Nginx config | | Keep legacy server running, idle | 2–4 weeks | Zero legacy hits, month-end passed | Re-enable upstream | | Archive and delete | 1 day | Backups verified, server removed | Restore from archive | The read-only period is the step people skip and regret. It flushes out hidden writers: the partner integration posting orders, the forgotten admin page. A simple guard in the legacy front controller is enough:{% raw %} ~~~php // legacy/index.php, top of file if (getenv('LEGACY_READ_ONLY') && $_SERVER['REQUEST_METHOD'] !== 'GET') { error_log('LEGACY WRITE BLOCKED: '.$_SERVER['REQUEST_URI']); http_response_code(503); exit('This page has moved. Please use the new app.'); } ~~~{% endraw %} ## After cutover: actually delete things Decommissioning means removal, not just "unused". Before deleting, archive the final code (tag the repo), take and test-restore a database snapshot, and export any files only the legacy app stored. Then remove, in order: proxy upstream entries, legacy cron jobs, DNS records for legacy hostnames (dangling records can become a takeover risk), firewall rules, credentials the old app used (rotate any shared with the new app), and finally the server itself. ## Decommissioning checklist - [ ] One week of routing logs reviewed; every legacy path has an owner and a decision. - [ ] Non-HTTP dependencies listed: cron, direct DB writers, IP-based callers. - [ ] Shadow comparisons run on read routes with numbers, including a month-end. - [ ] Remaining routes moved by percentage flag with rollback tested. - [ ] Legacy app read-only for at least a few days with zero blocked writes at the end. - [ ] Legacy server idle for 2–4 weeks with zero hits. - [ ] Code tagged, DB snapshot restored successfully, files exported. - [ ] DNS, cron, firewall rules, credentials and servers removed. ## FAQ ### How long should the whole decommission take? For a typical mid-sized business app, four to eight weeks from the first routing log to deleting the server, most of it waiting to see rare traffic such as month-end or quarterly jobs. ### Is Nginx mirroring safe for production load? It doubles requests for mirrored locations, so mirror selected read routes, not the whole site, and give the shadow upstream short timeouts so it cannot slow down users. ### What if shadow results never match exactly? Look at the differences. Often the legacy app had a bug (rounding, timezone) that users rely on. Decide with the business which behaviour is correct and document it before switching. ### Can I do this without Laravel Pennant? Yes. Any flag system works, even a config value plus a user ID hash. Pennant just makes per-user stickiness easy. ### What about SEO for public legacy URLs? Map old URLs to new ones with permanent 301 redirects and keep them for at least a year. Check search console for 404s after cutover. ### When is it safe to delete the legacy database? After the snapshot restore is tested and retention requirements are clear. Some industries need records for years; archive to cold storage rather than deleting outright. ## Series wrap-up Across six parts we ran old and new side by side, fixed module boundaries, upgraded PHP, moved auth, built a deploy pipeline, and finally turned the old app off. None of it needed a big-bang rewrite. If you have an inherited PHP system and want help taking it through this, see our [custom web application development](https://looporigin.com/services/custom-web-application-development?utm_source=devto&utm_medium=series&utm_campaign=decommissioning-legacy-app-cutover) work or [contact Loop Origin](https://looporigin.com/contact?utm_source=devto&utm_medium=series&utm_campaign=decommissioning-legacy-app-cutover) to talk about your app. --- ### Follow & Connect - **Website:** [Loop Origin](https://looporigin.com/?utm_source=devto&utm_medium=series&utm_campaign=decommissioning-legacy-app-cutover) - **Watch on YouTube:** [Resume Boost AI](https://www.youtube.com/@resume-boost-ai) · [PixelValut](https://www.youtube.com/@pixel-valut) · [Daily AI News By Ali](https://www.youtube.com/@AIDailyNewsByAli) - **LinkedIn:** [Loop Origin](https://www.linkedin.com/company/loop-origin) - **X:** [Muhammad Ali Mughal (@AliMughal887)](https://x.com/AliMughal887) - **GitHub:** [Loop Origin (@LoopOrigin)](https://github.com/LoopOrigin) 