Laravel Upgrade Guide: Pitfalls and Best Practices

Before You Start

Laravel upgrades range from "swap a version number" to "weeks of work." Before touching anything:

Check PHP requirements. Laravel 11 requires PHP 8.2. If you're on 8.0, upgrade PHP first.

Assess your test coverage. High coverage = confident upgrade. Low coverage = risky upgrade.

Check third-party packages. Run composer outdated and check each package supports your target Laravel version. This is often where upgrades get stuck.

---

Common Breaking Changes

Every major version breaks something. Here are the patterns:

Laravel 9 → 10:

Laravel 10 → 11:

The official upgrade guide covers everything, but these are the ones that catch people.

---

The Upgrade Process

Step 1: Branch and backup

Never upgrade on main. Create a branch and make sure you can restore if needed.

Step 2: Update PHP if necessary

Do this separately from the Laravel upgrade. One change at a time.

Step 3: Update composer.json

Change the laravel/framework version requirement. For major versions, you'll also need to update other first-party packages (laravel/sanctum, laravel/horizon, etc.).

Step 4: Run composer update

This is where you find out which packages don't support the new version yet.

Step 5: Compare config files

Create a fresh Laravel installation and compare config files. Look for new options and changed defaults.

Step 6: Run tests

Everything passing? Great. Tests failing? Fix them before continuing.

Step 7: Manual testing

Even with good test coverage, click around. Check the critical paths: login, main features, payments.

---

Testing Thoroughly

Your testing priority:

If you don't have automated tests, create a manual testing checklist:

• User can register
• User can log in
• User can reset password
• Main workflow completes
• Payment processes (test mode)
• Emails send correctly
• File uploads work
• Admin access works

---

Common Mistakes

Skipping versions. Going 8 → 11 in one jump is asking for trouble. Upgrade step by step: 8 → 9 → 10 → 11. It takes longer but each step is manageable.

Ignoring deprecation warnings. Those warnings become errors in the next version. Fix them as you see them.

Upgrading on Friday. Don't. Give yourself a full week to deal with issues.

Not checking the queue. Jobs pushed before the upgrade may fail after the upgrade if method signatures changed. Clear or drain your queues before deploying.

Rushing to production. Deploy to staging first. Let it sit for a day. Check logs. Then production.

---

Timeline expectations

If you're multiple versions behind and don't have tests, consider whether a gradual upgrade or a structured modernization makes more sense.

---

Need help?

We've upgraded dozens of Laravel applications, from quick version bumps to major overhauls of neglected codebases. If you're stuck or want to avoid the hassle, we can help.