Upgrade guide: Laravel 11 to 12

Upgrade steps and major changes when moving from Laravel 11 to 12.

Introduction

Laravel 12 was released in February 2025. This guide walks through upgrading from Laravel 11.x to 12.x.

Estimated time to upgrade is about 5 minutes. Actual impact from breaking changes depends on your app’s size and features you use.

Automated upgrades with Laravel Shift

You can automate the upgrade using Laravel Shift. Shift updates dependencies and configuration files automatically.

---

Changes by impact level

Impact: high

• Dependency updates
• Laravel installer update

Impact: medium

• Eloquent HasUuids trait and UUIDv7

Impact: low

• Carbon 3
• Concurrency result index mapping
• Container class dependency resolution
• SVG exclusion from image validation
• Default root path for the local filesystem disk
• Multi-schema database inspection
• Merging nested array requests

---

Upgrade steps

Update dependencies

Impact: high

Update the following dependencies in composer.json.

{
  "require": {
    "laravel/framework": "^12.0"
  },
  "require-dev": {
    "phpunit/phpunit": "^11.0",
    "pestphp/pest": "^3.0"
  }
}

Then install dependencies:

composer update

---

Update the Laravel installer

Impact: high

If you use the Laravel installer CLI to create new Laravel apps, update it to the version that supports Laravel 12.x and the new starter kits.

If installed via composer global require:

composer global update laravel/installer

If installed via php.new, run the reinstall command for your OS.

macOS

/bin/bash -c "$(curl -fsSL https://php.new/install/mac/8.4)"

Windows PowerShell

# Run as administrator
Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://php.new/install/windows/8.4'))

Linux

/bin/bash -c "$(curl -fsSL https://php.new/install/linux/8.4)"

If you use the Laravel Herd bundled version, update Herd itself to its latest release.

---

New starter kits

Laravel 12 introduces new starter kits to replace the previous Breeze and Jetstream. Running laravel new lets you interactively pick a frontend stack.

Available starter kits:

• React — Inertia 2, React 19, TypeScript, Tailwind 4, shadcn/ui
• Vue — Inertia 2, Vue Composition API, TypeScript, Tailwind 4, shadcn-vue
• Svelte — Inertia 2, Svelte 5, TypeScript, Tailwind 4, shadcn-svelte
• Livewire — Livewire, Tailwind 4, Flux UI

laravel new my-app

Running the command prompts you to choose a starter kit. After choosing, install dependencies and start the dev server.

cd my-app
npm install && npm run build
composer run dev

When upgrading existing apps, you don’t need to reinstall a starter kit. It’s a change for new projects.

---

Breaking changes

Eloquent

HasUuids trait and UUIDv7

Impact: medium

The HasUuids trait now returns UUID v7 (ordered UUIDs). To keep the previous ordered UUID v4 behavior, switch to the HasVersion4Uuids trait.

use Illuminate\Database\Eloquent\Concerns\HasUuids; // [tl! remove]
use Illuminate\Database\Eloquent\Concerns\HasVersion4Uuids as HasUuids; // [tl! add]

If you previously used the HasVersion7Uuids trait, switch to HasUuids (which now has the same behavior).

---

Validation

SVG exclusion from image validation

Impact: low

The image validation rule no longer allows SVG by default. To allow SVG, specify it explicitly.

use Illuminate\Validation\Rules\File;

'photo' => 'required|image:allow_svg'

// Or
'photo' => ['required', File::image(allowSvg: true)],

---

Storage

Default root path for the local filesystem disk

Impact: low

If the local disk isn’t explicitly defined in the filesystems configuration, its default root path has changed from storage/app to storage/app/private.

To keep the previous behavior, define the local disk explicitly in the configuration file.

// config/filesystems.php
'local' => [
    'driver' => 'local',
    'root' => storage_path('app'),
],

---

Database

Multi-schema database inspection

Impact: low

Schema::getTables(), Schema::getViews(), and Schema::getTypes() now return results from all schemas by default. To target only a specific schema, pass the schema argument.

// Tables from all schemas
$tables = Schema::getTables();

// Tables from only the 'main' schema
$tables = Schema::getTables(schema: 'main');

Schema::getTableListing() now returns schema-qualified table names by default.

$tables = Schema::getTableListing();
// ['main.migrations', 'main.users', 'blog.posts']

$tables = Schema::getTableListing(schema: 'main', schemaQualified: false);
// ['migrations', 'users']

Database constructor signature change

Impact: very low

Illuminate\Database\Schema\Blueprint and Illuminate\Database\Grammar constructors now require a Connection instance as their first argument.

// Laravel <= 11.x
$grammar = new MySqlGrammar;
$grammar->setConnection($connection);

// Laravel >= 12.x
$grammar = new MySqlGrammar($connection);

The following APIs are also deprecated or removed.

API	Status
Blueprint::getPrefix()	Deprecated
Connection::withTablePrefix()	Removed
Grammar::getTablePrefix() / setTablePrefix()	Deprecated
Grammar::setConnection()	Removed

Get the table prefix directly from the connection.

$prefix = $connection->getTablePrefix();

---

Concurrency

Result index mapping

Impact: low

When you pass an associative array to Concurrency::run(), results are now returned associated with their keys.

$result = Concurrency::run([
    'task-1' => fn () => 1 + 1,
    'task-2' => fn () => 2 + 2,
]);

// ['task-1' => 2, 'task-2' => 4]

---

Container

Default values in class dependency resolution

Impact: low

The DI container now respects default class property values when resolving class instances.

class Example
{
    public function __construct(public ?Carbon $date = null) {}
}

$example = resolve(Example::class);

// Laravel <= 11.x: returns a Carbon instance
// Laravel >= 12.x: returns null

---

Requests

Merging nested array requests

Impact: low

$request->mergeIfMissing() can now merge nested array data using dot notation. Previously, dot-notation keys were created as top-level keys as-is.

$request->mergeIfMissing([
    'user.last_name' => 'Otwell',
]);

---

Routing

Route priority

Impact: low

The behavior when multiple routes have the same name is now consistent between cached and uncached routing. Even without caching, the first-registered route now wins instead of the last.

---

Authentication

DatabaseTokenRepository constructor change

Impact: very low

The Illuminate\Auth\Passwords\DatabaseTokenRepository constructor’s $expires parameter now takes seconds rather than minutes.

---

Carbon 3

Impact: low

Carbon 2.x support has been dropped. All Laravel 12 apps require Carbon 3.x.

---

Summary

Laravel 12 is a comparatively smooth upgrade. Here are the main things to watch out for.

Change	Impact	Action
Update composer.json dependencies	High	Set laravel/framework ^12.0
Update the Laravel installer	High	composer global update
HasUuids → UUIDv7	Medium	Switch to HasVersion4Uuids if needed
SVG exclusion from image validation	Low	Add allow_svg to allow SVG
Default root of local disk changed	Low	Specify explicitly in config
Carbon 3 required	Low	Verify API compatibility

---

References

• Official upgrade guide (English)
• laravel/laravel diff (11.x → 12.x)
• New starter kits
• Laravel Shift — community service to automate upgrades
• Carbon 3 migration guide