Upgrade Laravel 12 to 13: Steps and Breaking Changes

Laravel 13 came out on March 17, 2026, and moving a Laravel 12 app to it is a small job: the official upgrade guide estimates about 10 minutes. You need PHP 8.3 or higher, a few version bumps in composer.json, and a check of one renamed middleware plus two settings that can change behaviour. This guide walks through the steps in order, explains each breaking change in plain terms, and lists the errors you are most likely to hit. Details are as of November 2026.

Quick answer

If you only need the short version, this is it:

• Laravel 13 needs PHP 8.3 or higher (it supports 8.3 to 8.5).
• Change laravel/framework to ^13.0, then update the related packages listed below and run composer update.
• The only high-impact code change is the CSRF middleware rename to PreventRequestForgery. The old names still work as deprecated aliases.
• Check your cache config if you store PHP objects in the cache, and your session settings if you plan to switch to JSON.

Before you start: check PHP and back up

Laravel 13 will not install on older PHP, so check this first. Run php -v on every machine that runs your app: your laptop, CI and the server. If any of them is below 8.3, upgrade PHP before you touch Laravel, or Composer will refuse to resolve the new version.

Then create a new git branch and commit everything. The upgrade is small, but a clean branch makes it easy to see exactly what changed and to roll back if a package blocks you. If you use a staging server, upgrade there first.

Step by step: upgrade Laravel 12 to 13

These are the steps from the official Laravel 13 upgrade guide, with a few practical checks added between them.

1. Edit composer.json. Set laravel/framework to ^13.0. Also update these if your app uses them: laravel/boost to ^2.0, laravel/tinker to ^3.0, phpunit/phpunit to ^12.0 and pestphp/pest to ^4.0.
2. Run composer update. Read the output. If Composer reports a conflict, it will name the package that does not yet allow Laravel 13.
3. Update the Laravel installer if you create new projects with it: composer global update laravel/installer. If you use Laravel Herd, update Herd instead.
4. Confirm the version with php artisan --version.
5. Apply the high and medium changes described in the next section.
6. Run your tests and click through login, forms and anything that uses the cache or queues.

The guide also offers an optional shortcut. If you install Laravel Boost (^2.0) in your Laravel 12 app, you can run the /upgrade-laravel-v13 command in an AI coding tool such as Claude Code, Cursor or VS Code. Treat what it produces like any other pull request and review the diff. Laravel Shift, a paid community service, can also open an upgrade pull request for you.

Breaking changes that matter

Laravel lists one high-impact change, two medium-impact changes and a longer set of low-impact ones. Here is what the first three mean for a real app.

1. CSRF middleware renamed (high impact)

VerifyCsrfToken is now PreventRequestForgery. The old VerifyCsrfToken and ValidateCsrfToken names remain as deprecated aliases, so most apps keep working, but you should rename any reference now. The new middleware also checks where a request came from using the Sec-Fetch-Site header, and it still works with normal token-based CSRF protection.

If you exclude routes from CSRF checks, change the class in withoutMiddleware:

use Illuminate\Foundation\Http\Middleware\PreventRequestForgery;

// Laravel 12
->withoutMiddleware([VerifyCsrfToken::class]);

// Laravel 13
->withoutMiddleware([PreventRequestForgery::class]);

The configuration API also gains a preventRequestForgery(...) method.

2. Cache serializable_classes now defaults to false (medium)

The default cache config now sets serializable_classes to false. If your app deliberately stores PHP objects in the cache, list those classes in the allow-list or switch to arrays:

'serializable_classes' => [
    App\Data\CachedDashboardStats::class,
],

This is a security tightening, since unserialising arbitrary objects from a cache is a known risk. If you only cache strings, numbers and arrays, you can ignore it.

3. upsert with MySQL or MariaDB (medium)

Passing an empty uniqueBy to upsert now throws an InvalidArgumentException. MySQL and MariaDB ignore uniqueBy and rely on primary and unique indexes, but the argument is still validated. Search your code for upsert( and make sure the argument is not empty.

Low-impact changes worth a quick search

The guide also lists smaller items, including cache prefixes and session cookie names, the QueueBusy event property rename, JobAttempted event payloads, pagination Bootstrap view names and polymorphic pivot table naming. Search your app for the ones you use. One to know about: if you change the session serialization option from php to json, all active sessions are invalidated and every user is logged out once.

Common errors and how to fix them

• Composer says a package conflicts with laravel/framework ^13.0. That package has not released a Laravel 13 version, or its constraint is too tight. Check its releases for a newer tag, or hold the upgrade until it supports 13.
• Composer says your PHP version does not satisfy the requirement. Upgrade PHP to 8.3 or higher on the machine running Composer. Also check the php value under config.platform in composer.json, which can pin an older version.
• Tests fail after bumping PHPUnit or Pest. Moving to PHPUnit 12 or Pest 4 is a separate upgrade with its own changes. If this slows you down, upgrade Laravel first, get green tests, then bump the test tools in a second commit.
• Cached objects stop working. This points to the serializable_classes change above. Add the classes to the allow-list or cache plain arrays.
• Everyone is logged out after deploy. Expected if you changed the session serialization or cookie name. Plan it for a quiet hour and tell users.

What you get after upgrading

You do not have to use any of these, but they explain why teams upgrade. According to the Laravel 13 release notes, the headline additions are the first-party Laravel AI SDK, JSON:API resources, PHP attributes such as #[Middleware] and #[Authorize] on controllers, Queue::route(...) for sending job classes to a chosen queue, Cache::touch(...) to extend a cache item without reading it, and vector similarity queries on PostgreSQL with pgvector.

Support dates

Should you upgrade now?

Upgrade now if your app is on PHP 8.3 or higher and your key packages support Laravel 13. The upgrade is low risk, and staying on an older major version eventually means losing security fixes. Wait if a package you cannot replace has no Laravel 13 release yet, or if your server is stuck on PHP 8.2. In that case, plan the PHP upgrade first, since it is the real prerequisite.

If you care about the security side of keeping software current, our post on AI-found Linux kernel bugs covers why patching promptly matters.

Frequently asked questions

How long does it take to upgrade Laravel 12 to 13?

The official guide estimates about 10 minutes for the framework change itself. Budget more time for testing, and extra if you also move to PHPUnit 12 or Pest 4.

Which PHP version does Laravel 13 need?

PHP 8.3 or higher. Laravel 13 supports PHP 8.3 through 8.5.

Will my old VerifyCsrfToken code break?

Not straight away. VerifyCsrfToken and ValidateCsrfToken stay as deprecated aliases, but you should switch to PreventRequestForgery so you are not relying on names that may be removed later.

Do I have to use the Laravel AI SDK after upgrading?

No. It is a new first-party package for text, images, audio and embeddings. Your existing app does not need it to run on Laravel 13.

Can I skip tests and just deploy?

You can, but it is a bad idea. The risky parts are your own cache usage, session settings and third-party packages, and only your tests or a staging check will show those.