Laravel
Laravel 12 to 13: a practical upgrade checklist
Plan a Laravel 12-to-13 upgrade with dependency checks, targeted regression testing, staging validation and a release plan that protects new production data.
A framework upgrade is complete when the application still performs its important jobs. A successful Composer update is one checkpoint, not the finish line.
This checklist is for an existing Laravel 12 application moving to Laravel 13. Use it alongside the official upgrade guide; it is not a replacement for the full list of compatibility changes.
1. Establish a working baseline
Create an upgrade branch and start with a reproducible installation from the current lockfile. Record the PHP versions used by the web server, CLI, queue workers and CI. They can differ even when they run on the same machine.
Run the existing tests before changing dependencies. If a test already fails, record that separately rather than letting it disappear into a long upgrade failure list.
php -v
php artisan --version
composer validate
composer check-platform-reqs
php artisan test
These commands inspect or exercise your local application. Run tests with the intended test environment and database, not production credentials.
2. Check the platform and package constraints
Laravel 13 requires PHP 8.3 or newer. Confirm the supported version range and release policy in the Laravel 13 release notes, then check every runtime you deploy.
Inspect installed packages before editing constraints:
composer show --direct
composer why-not laravel/framework '^13.0'
Review blockers individually. An abandoned package, an incompatible admin panel and an outdated test runner need different fixes. Do not remove a dependency just to satisfy the solver without checking which feature uses it.
Update the framework constraint and relevant installed tools according to the upgrade guide. Review the resulting lockfile and changelog rather than assuming every transitive change is harmless. Commit the manifest and lockfile together.
3. Translate compatibility changes into app-specific checks
The official guide flags request-forgery protection, cache serialisation and MySQL/MariaDB upsert behavior among the areas to review. It also documents changes that can affect default cache prefixes and session cookie names.
Use those topics to find the code paths that matter in your application:
| Application feature | Regression check |
|---|---|
| Session-backed forms | Valid submissions succeed; invalid requests are rejected |
| External callbacks | The intended authenticated callback still works without broadly bypassing protection |
| Database imports | Unique keys and upsert outcomes match your expectations |
| Cached objects | Expected values survive a write/read cycle |
| Login sessions | Cookie names, domains and continuity match the release plan |
| Background jobs | A queued job can be dispatched, processed and observed |
Only investigate changes that apply to your configuration, but make that decision explicitly. Avoid copying a fresh application’s entire configuration directory over a working app: it can erase intentional settings.
4. Test representative business journeys
Run automated tests after dependency installation. Then exercise the journeys whose failure would interrupt the business: authentication, payment callbacks where relevant, uploads, exports and notifications.
Include permission failures. A user should still be prevented from viewing another account’s records, even when the primary dashboard works perfectly.
If the application uses a compiled frontend, build its assets in the same way CI will. Check that the result loads without missing files and that validation messages appear where users expect them. A backend-only test suite will not catch every frontend integration problem.
For a new frontend direction, read Livewire vs Inertia for a searchable dashboard, but keep that redesign separate from the framework upgrade where practical. Smaller releases are easier to diagnose.
5. Rehearse the deployment on staging
Use representative configuration and data while protecting personal information. Confirm environment variables, writable storage, database connectivity, queue processing and scheduled work.
Document the project’s exact release sequence, including how long-running processes reload the new code. Verify that the new release is serving requests and processing a test job; copying files alone does not establish that every process has switched versions.
Record observable results: a test enquiry arrives, an export completes and a failed action displays its expected message. These are stronger release signals than “the homepage looks fine.”
6. Plan rollback around data changes
Know how to restore the previous code release and whether any database migration prevents that code from running. Prefer backwards-compatible schema changes when the release process requires old and new workers to coexist.
Do not casually restore an old production database if new orders, tickets or registrations have arrived since the backup. Recovery must account for that new information. Rehearse the procedure before depending on it.
After release, check error reporting and repeat the critical journeys with appropriate test inputs. Keep a short release record showing the versions, validation results and recovery approach.
A useful definition of done
The upgrade is ready when dependencies resolve on the target platform, applicable compatibility changes have been reviewed, critical journeys pass and the recovery process is understood. The elapsed time depends on the application, its packages and its existing tests.
If an AI feature is planned next, compare Laravel AI SDK and direct API calls in a separate release. Establishing a reliable baseline makes that later change easier to evaluate.