Upgrading Laravel one major version at a time
Published by PWTECH
Laravel ships a major release every year and supports each one for a limited time. An application that stays on one version for three or four years is not broken, but it is cut off: security fixes stop, newer packages refuse to install, and the hosting provider eventually drops the PHP version it needs.
The temptation is to jump straight to the newest release in one move. We do the opposite. Each major version has an upgrade guide written for the version before it, and following them in sequence turns one large unknown into a series of small, documented steps.
What accumulates while an application waits
Abandoned packages
A community package that worked fine on an older release may have no maintainer today. Every version skipped adds more of these, and each one needs a replacement or a fork before the framework itself can move.
PHP version steps
Each Laravel release raises the minimum PHP version. Moving two or three PHP versions at once brings its own deprecations, from dynamic properties to changed function signatures, mixed in with the framework changes.
Silent behaviour changes
Some changes do not throw errors. A default that flipped, a date cast that now returns an immutable object, a queue option renamed. With one version at a time, the diff is small enough to read.
Tests that nobody ran
A test suite that has not been run for a year usually fails for reasons unrelated to the upgrade. Separating those failures from real regressions is easier when the framework has only moved one step.
How we run an upgrade
Read composer.json first
The lock file tells us the framework version, the PHP constraint and every package. We list the packages that have no release for the target version before anything is touched.
Get the tests green where they are
Before moving, the existing suite has to pass on the current version. If there is no suite, we write feature tests for sign-in, payments and whatever the business would notice first.
Move one major version
Follow that release's upgrade guide line by line, update first-party packages to their matching versions, then run the suite. A failure now points at one change, not at a year of them.
Fix, commit, repeat
Each version lands as its own commit or pull request, so a problem found later can be traced to the step that introduced it. Then the next guide.
Deploy to a staging copy
The final version runs on a copy of production with a recent database before the live switch, because some problems only appear with real data volumes and real cron schedules.
Six things worth checking in advance
- Which PHP versions your host offers, and whether you can switch per site
- Whether the queue worker and scheduler are supervised, so they can be restarted after each step
- Where sessions and cache live, since a driver change can sign everyone out
- Any code that reads framework internals directly rather than through the documented API
- Custom Blade directives, macros and service providers, which break quietly
- A restorable backup of the database and uploaded files, rehearsed once
Asked about Laravel upgrades
How long does one step take?
For a typical business application, a single major version is a few days of work including testing. The first step is usually the longest because it absorbs the neglected packages and the PHP move.
Can the application stay online during the upgrade?
Yes. The work happens on a branch and a staging copy. Production changes only at the end, in a planned window, with the previous release ready to restore.
Is it cheaper to rewrite?
Rarely. A rewrite throws away rules that nobody wrote down. An upgrade keeps them. We suggest a rewrite only when the application was never structured as a Laravel application in the first place.
Tell us which version you are on
The Laravel and PHP versions, where it is hosted and roughly how large the codebase is are enough for a first opinion. We reply within one business day.