Upgrading from Laravel 9 to 10

Upgrade steps and major changes for moving from Laravel 9.x to 10.x.

Introduction

Laravel 10 was released on February 14, 2023. This guide walks through the upgrade from Laravel 9.x to 10.x.

Estimated time to upgrade is about 10 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 with Laravel Shift. Shift updates dependencies and configuration files automatically.

---

Changes by impact level

Impact: high

• Dependency updates
• minimum-stability update

Impact: medium

• Database expression changes
• Removal of the model $dates property
• Monolog 3
• Redis cache tags
• Service mocking changes
• The language directory

Impact: low

• Closure validation rule messages
• The after method on form requests
• Public path binding
• QueryException constructor
• Rate limiter return value
• Removal of Redirect::home
• Removal of Bus::dispatchNow
• The registerPolicies method
• ULID columns

---

Upgrade steps

Update dependencies

Impact: high

Update the following dependencies in composer.json.

{
  "require": {
    "laravel/framework": "^10.0",
    "laravel/sanctum": "^3.2",
    "doctrine/dbal": "^3.0",
    "spatie/laravel-ignition": "^2.0"
  }
}

If you use these packages, update them too.

{
  "require": {
    "laravel/passport": "^11.0",
    "laravel/ui": "^4.0"
  }
}

If you’re using PHPUnit 10, also update:

{
  "require-dev": {
    "nunomaduro/collision": "^7.0",
    "phpunit/phpunit": "^10.0"
  }
}

With PHPUnit 10, remove the processUncoveredFiles attribute from the <coverage> section of phpunit.xml.

Then install dependencies:

composer update

For Sanctum 2.x → 3.x, also consult the Sanctum 3.x upgrade guide.

---

Update minimum-stability

Impact: high

Update minimum-stability in composer.json to stable. Since stable is the default, you can also remove this setting altogether.

"minimum-stability": "stable"

---

PHP version requirement

Impact: high

Laravel 10 requires PHP 8.1.0 or later and Composer 2.2.0 or later.

---

Breaking changes

Application

Public path binding

Impact: low

If you customize the public path by binding path.public in the container, switch to Illuminate\Foundation\Application’s usePublicPath method.

app()->usePublicPath(__DIR__.'/public');

---

Authorization

The registerPolicies method

Impact: low

The framework now calls AuthServiceProvider’s registerPolicies method automatically. You can remove the manual call from boot.

---

Cache

Redis cache tags

Impact: medium

Cache::tags() is recommended only for apps using Memcached. If you use Redis as your cache driver, consider migrating to Memcached.

---

Database

Database expression changes

Impact: medium

Database expressions produced by DB::raw have been rewritten. To get the raw string value of an expression, use the getValue(Grammar $grammar) method. Casting to (string) no longer works.

use Illuminate\Support\Facades\DB;

$expression = DB::raw('select 1');

// Before
$string = (string) $expression;

// After
$string = $expression->getValue(DB::connection()->getQueryGrammar());

Most end-user apps aren’t affected, but if you cast database expressions to string, updates are required.

QueryException constructor

Impact: very low

The Illuminate\Database\QueryException constructor now takes a connection name string as the first argument. If you manually throw this exception, adjust the code.

ULID columns

Impact: low

When you call the ulid method in a migration without arguments, the column name is now ulid. In previous releases, calling it without arguments incorrectly created a column named uuid.

// The column name becomes "ulid"
$table->ulid();

// Specify a column name explicitly if needed
$table->ulid('ulid');

---

Eloquent

The model $dates property

Impact: medium

The deprecated $dates property on Eloquent models has been removed. Use the $casts property instead.

// Before
protected $dates = ['deployed_at'];

// After
protected $casts = [
    'deployed_at' => 'datetime',
];

---

Localization

The language directory

Impact: none

Existing apps aren’t affected, but new Laravel application skeletons no longer include the lang directory by default. Publish it via an Artisan command if needed.

php artisan lang:publish

---

Logging

Monolog 3

Impact: medium

Laravel’s Monolog dependency has been updated to Monolog 3.x. If you use Monolog directly in your app, review the Monolog upgrade guide.

If you use third-party logging services like BugSnag or Rollbar, you may need to upgrade to versions that support both Monolog 3.x and Laravel 10.x.

Monolog 3.x changes are documented in the Monolog 3.x upgrade guide.

---

Queue

Removal of Bus::dispatchNow

Impact: low

The deprecated Bus::dispatchNow and dispatch_now methods have been removed. Use Bus::dispatchSync and dispatch_sync.

// Before
Bus::dispatchNow(new MyJob());
dispatch_now(new MyJob());

// After
Bus::dispatchSync(new MyJob());
dispatch_sync(new MyJob());

---

Routing

Middleware aliases

Impact: optional

In new Laravel apps, App\Http\Kernel’s $routeMiddleware property was renamed to $middlewareAliases. Applying it to existing apps is optional.

Rate limiter return value

Impact: low

When you call RateLimiter::attempt, the return value of the provided closure is now returned as-is. If you return nothing or null, true is returned.

$value = RateLimiter::attempt('key', 10, fn () => ['example'], 1);

$value; // ['example']

Removal of Redirect::home

Impact: very low

The deprecated Redirect::home method has been removed. Redirect to a named route explicitly.

// Before
return Redirect::home();

// After
return Redirect::route('home');

---

Testing

Service mocking

Impact: medium

The deprecated MocksApplicationServices trait has been removed from the framework. It provided test methods like expectsEvents, expectsJobs, and expectsNotifications.

If you use these methods, migrate to Event::fake, Bus::fake, and Notification::fake respectively.

// Before
$this->expectsEvents(OrderShipped::class);

// After
Event::fake();
// ... test code ...
Event::assertDispatched(OrderShipped::class);

---

Validation

Closure validation rule messages

Impact: very low

In closure-based custom validation rules, calling $fail multiple times now appends messages to an array instead of overwriting.

Also, the $fail callback now returns an object. If you type-hint the return value of a validation closure, update it.

public function rules()
{
    return [
        'name' => [
            function ($attribute, $value, $fail) {
                $fail('validation.translation.key')->translate();
            },
        ],
    ];
}

The after method on form requests

Impact: very low

Laravel now reserves an after method on form requests. If your form request defines an after method, rename it or migrate to the new “after validation” feature.

---

Summary

Laravel 10 involves relatively small changes, and the upgrade can be completed quickly.

Change	Impact	Action
Update composer.json dependencies	High	Set laravel/framework ^10.0
PHP 8.1 / Composer 2.2 required	High	Verify and update versions
Database expression changes	Medium	Replace (string) cast with getValue()
Model $dates property removed	Medium	Migrate to $casts
Monolog 3	Medium	Check the upgrade guide if used directly
Redis cache tags	Medium	Consider migrating to Memcached
MocksApplicationServices removed	Medium	Migrate to Event::fake and friends
Bus::dispatchNow removed	Low	Use Bus::dispatchSync
ULID column name	Low	Review ulid() calls in migrations
Redirect::home removed	Very low	Use Redirect::route('home')

---

References

• Official upgrade guide (English)
• laravel/laravel diff (9.x → 10.x)
• Laravel Shift — community service to automate upgrades
• Sanctum upgrade guide (2.x → 3.x)
• Monolog 3.x upgrade guide