Laravel Upgrade and Modernization Checklist: Upgrade in Place, Replace in Stages or Rewrite

The short answer

Laravel's support policy sets the deadline: for every release, bug fixes are provided for 18 months and security fixes for 2 years, and major releases arrive every year, around the first quarter. An application that skips two annual upgrades is running a framework that no longer gets security fixes. For most applications the answer is an in-place upgrade, one major version at a time, with tests written first. Replacing the application in stages or rewriting it is for cases where the code cannot be upgraded safely, and the table below says when.

Where each version stands

From Laravel's release table and PHP's supported-versions page, as shown on October 10, 2026:

So on that date Laravel 13 is the only release still receiving bug fixes, Laravel 12 receives security fixes only, and Laravel 11 and earlier receive nothing.

PHP's policy is that each branch is fully supported for two years, then supported for two more years for critical security issues only. The two tables have to be read together: the framework and the language each have their own clock, and the application is unsupported as soon as either one runs out.

One reading of the first table is worth planning around. PHP 8.3 is the only PHP version inside the supported range of Laravel 10, 11, 12 and 13. An application on Laravel 10 can therefore move to PHP 8.3 first and then take three framework upgrades without touching the PHP version again, which keeps each step to one kind of change.

Upgrade in place, replace in stages, or rewrite

There are three routes. An in-place upgrade keeps the codebase and moves it through each major version. Replacing in stages is the strangler fig approach Martin Fowler describes as a gradual process of modernization: new code is built on top of, yet separate to the legacy code base, and behavior moves across piece by piece. A rewrite builds a replacement and switches over. Fowler's warning about the third is direct: replacement looks simple, but he has seen this simple-sounding plan go down in flames most of the time.

If the answers fall mostly in the first column, the rest of this guide is the plan. If they fall in the second, the same phases apply to each slice you move. Mixed answers are normal: upgrade the conventional core in place and replace the two or three areas that block it.

Phase 0: inventory

• Record the exact Laravel version from composer.lock, the PHP version in production (not only on a laptop), and the database engine and version.
• Check the database against what the target Laravel supports: MariaDB 10.3+, MySQL 5.7+, PostgreSQL 10.0+, SQLite 3.26.0+ and SQL Server 2017+ for Laravel 13.
• Run composer outdated, which shows a list of installed packages that have updates available.
• Run composer audit, which lists security vulnerability advisories and detects abandoned packages. Every abandoned package needs a named replacement before you start.
• For the target version, run composer why-not laravel/framework with that version. The command tells you which packages are blocking a given package from being installed; its output is your list of blockers.
• Search for edits inside vendor, forked packages and classes that extend framework internals. These are what turn a short upgrade into a long one.
• List everything that runs outside a web request: queue workers, scheduled tasks, cron entries that bypass the scheduler, and long-running services.
• Note the test count and what the tests cover. Zero is an answer; write it down.

Phase 1: build the safety net

• Write feature tests for the paths that earn or move money, sign users in, and change permissions. Laravel's own advice is that most of your tests should be feature tests, because they exercise a full request.
• Run the tests in CI on every push, on the PHP version production uses.
• Add static analysis at a level the code passes today. PHPStan has 11 levels, 0 the loosest and 10 the strictest, and a baseline that records current errors so only new and changed code is reported. Larastan is the PHPStan extension for Laravel.
• Fix code style once, in its own commit, so later diffs show only real changes. Laravel Pint is built on PHP CS Fixer and has a --test option that reports style errors without changing files.
• Stand up a staging environment with the same PHP, database and queue driver as production, and a recent copy of production data with personal data masked.
• Confirm you can restore a database backup, by doing it.
• Turn on error tracking and a baseline of response times before the first change, so you can tell what the upgrade altered.

Phase 2: move PHP first

• Pick the highest PHP version your current Laravel supports, from the first table, and move to it before changing the framework.
• Read the PHP migration guide for each version you cross. Each has a section on backward incompatible changes and deprecated features.
• Run the test suite with deprecation notices visible and clear them; a deprecation in one PHP version is often a removal in a later one.
• Use Rector for mechanical changes. It describes itself as fast, deterministic PHP code upgrades and automated refactoring. Review its diff like any other pull request.
• Deploy the PHP change on its own and let it run in production before the first framework step.

Phase 3: one major version at a time

Laravel publishes one upgrade guide per major version, each written from the version before it: the Laravel 6 guide is titled Upgrading To 6.0 From 5.8 and the current one Upgrading To 13.0 From 12.x. Each guide sorts its changes by likelihood of impact. Do not skip a guide; an application three versions behind has three guides to work through.

For every step:

• Read the whole guide for that version and mark the items that touch code you use.
• Update laravel/framework and the packages the guide lists, then resolve what composer why-not reports.
• Apply the high-impact changes, then the medium ones, then search the code for each low-impact item.
• Optionally run the community Rector rules for Laravel for that version.
• Run tests and static analysis; fix; repeat until clean.
• Deploy to staging, run the non-web jobs from your inventory by hand, then release.
• Let the release run in production before starting the next step.

What Laravel's own guides flag for the last four steps:

Read those estimates for what they are. Laravel says it strives to ensure you may update to a new major release in one day or less, and the minutes cover the framework's own breaking changes. They do not include third-party packages that have not released a compatible version, code that leans on undocumented behavior, or the time to test. The inventory in Phase 0 is what tells you how far your application is from the estimate.

Two automation options are named in the Laravel 13 guide: Shift, which it calls a community-maintained service that automates Laravel upgrades, and Laravel Boost, a first-party MCP server that provides an AI assistant with guided upgrade prompts. Either can produce the first diff. Neither replaces the tests that tell you whether the diff is right.

Phase 4: deploy and verify

• Use maintenance mode only if a migration needs it; php artisan down shows a custom view for all requests while it is on.
• Rebuild caches as part of the deploy: the optimize command caches configuration, events, routes and views.
• Restart workers. Queue workers are long-lived processes and will not notice changes in your code base; the deployment guide's reload command terminates queue workers, Reverb and Octane so they start on the new code.
• Drain or version queued jobs whose payload shape changed, so a job serialized by the old release is not run by the new one unprepared.
• Confirm APP_DEBUG is false: Laravel warns that with it on in production you risk exposing sensitive configuration values.
• Point your uptime monitor at the health route, which is served at /up and returns 200 if the application has booted without exceptions.
• Watch error rate, slow requests and failed jobs against the baseline from Phase 1. Laravel Pulse tracks slow jobs and endpoints if you have no other tool.
• Keep the previous release and a database backup ready until the new one has run through a full business cycle, including scheduled jobs.

Phase 5: modernize after you are current

Upgrading gets you onto a supported version. Modernizing is what makes the next upgrade short. Do it after, as separate changes:

• Replace each abandoned or forked package with a maintained one or with framework features that have since been added.
• Raise the static-analysis level one step at a time and shrink the baseline.
• Move logic out of controllers and closures into classes that can be tested without a request.
• Squash old migrations: schema:dump writes them into a single SQL file.
• Move loose cron entries into the scheduler so the schedule is in source control.
• Decide deliberately whether to adopt the newer application structure; it is optional, and Laravel 11 was tuned to also support the Laravel 10 application structure.
• Put the next upgrade on the calendar. With a major release each year and security fixes for two, one upgrade a year keeps an application inside support.

If the application is plain PHP or very old

Here the staged route usually fits. Put a new Laravel application in front of the same domain, send it the routes it implements and pass everything else to the old code. Fowler's article lists what an incremental replacement needs, starting with understanding the outcomes you want to achieve and deciding how to break the problem up into smaller parts. In practice the first decisions are technical: how the two sides share a login session, which side owns each database table, and how a route is switched back if the new version misbehaves. Move a read-only area first, then one with writes, and retire old code as each route leaves it. The checklist above then applies to the new side from its first day.

Older Laravel versions also need older PHP steps on the way: the Laravel 9 guide, for example, required PHP 8.0.2 or greater and estimated 30 minutes, with Flysystem 3 and Symfony Mailer as its high-impact changes. Count the hops in Phase 0 before choosing between an in-place upgrade and a staged replacement.

Versions, dates and support windows were read from the linked Laravel, PHP, Composer, PHPStan, Rector and Larastan pages on October 10, 2026. Both support tables change with every release, so check them again before you plan. This guide is drawn from that documentation; Peregrine has not published a Laravel case study, and nothing here describes a client project.

Need a second opinion on an upgrade plan? See our Laravel development service, or read how we approach API integration when the upgrade also touches third-party systems. Engagements are fixed-scope projects, monthly retainers, or a combination, agreed after a 30-minute technical discovery call.