Laravel Upgrade Checklist

Upgrades go wrong when several major versions are changed at once without tests. This checklist follows the safer route: prepare, add a safety net, upgrade one major version at a time, then release with a rollback plan. Always follow the official Laravel upgrade guide for the exact changes in each version.

Before you start

• Note the current Laravel and PHP versions (php artisan --version, php -v).
• Read the official upgrade guide for each major version you will pass through.
• List every Composer package and check which ones support the target Laravel version.
• Find abandoned packages and choose replacements before you begin.
• Check that your server, hosting or Docker image can run the PHP version the target release needs.
• Make sure you have a full database backup and can restore it.
• Agree a code freeze or a branch strategy with the team.

Tests and safety net

• Run the existing test suite and fix tests that already fail.
• Add tests around the most important flows: login, payments, checkout, reports, imports.
• Set up error tracking and logs so new errors are visible after release.
• Prepare a staging environment that matches production.

Upgrade, one major version at a time

• Upgrade PHP first if the target version needs it, and run the tests.
• Update composer.json to the next major Laravel version only — never skip several at once.
• Update first-party packages (Sanctum, Horizon, Telescope, Cashier and so on) to matching versions.
• Run composer update and fix dependency conflicts.
• Work through each "high impact" and "medium impact" change in the official guide.
• Compare config files with a fresh install of the same version and copy over new options.
• Consider automated refactoring (for example Rector with Laravel rules) and review every change it makes.
• Run the tests, fix failures, then repeat for the next major version.

Code and behaviour checks

• Search for deprecated helpers, facades and methods removed in the new version.
• Check queues, scheduled tasks and events still run as expected.
• Check authentication, password resets and API tokens.
• Check file uploads, storage disks and email sending.
• Rebuild front-end assets if the upgrade changes the build tooling.
• Clear and rebuild caches: config, routes, views and events.

Release

• Test the full release on staging with a copy of production data.
• Write down the rollback steps and test them once.
• Deploy at a quiet time and watch error tracking closely for the first hours.
• Restart queue workers after deployment so they load the new code.
• Keep the old release available until you are confident the upgrade is stable.

Related

Laravel development · CodeIgniter to Laravel migration · Symfony upgrade services · Laravel vs Symfony