The right way to upgrade Laravel

Staying up to date with Laravel and your packages is important. Not only can you use the latest features, but you get security and bug fixes as they're available.

But when it comes time for a major version bump in Laravel, you have a choice as to how you want to do the upgrade.

With both approaches I'm going to describe, you should definitely start by reading the Laravel upgrade guide. This will highlight breaking changes and other important changes you should be aware of.

Armed with that knowledge, the simple upgrade path would look like this:

• bump the major version in your composer.json file and run composer update
• address all the breaking/important changes from the upgrade guide
• make sure tests pass

That approach will get you the benefits of the latest version of Laravel, but in my opinion, it still falls a bit short.

Instead, my desire when upgrading Laravel is to make it look like the application was built on the new version from the start. What's the difference?

It can be quite a lot! Changes to config keys or default values, new defaults in service providers, changes to the default middleware stack, validation message changes, and more.

I like to do a diff between a fresh Laravel install on the new version and my application to identify these changes, and then merge them in.

This was especially evident in the upgrade from Laravel 10 to 11 where a lot of the application skeleton was slimmed and reorganized.

The Laravel 10 code still works, but it's not going to feel like a Laravel 11 application. And that difference will grow over time.

I really like to stick with defaults and conventions, so juggling a few different ways of bootstrapping an app across projects is not something I want to do.

If this sounds like it's not worth the effort, I'd encourage you to try it once and compare. Even better, use a tool like Laravel Shift which automates most of the work for you. The few dollars you spend will save you a bunch of time and result in a more meticulous upgrade.

Here to help,

Joel

P.S. Small, steady improvements keep your app healthy. The same is true for security. Check out our free 7 Steps to a Secure Laravel App book.