Laravel 10.x Upgrade Guide

High Impact Changes

Medium Impact Changes

Low Impact Changes

Upgrading To 10.0 From 9.x

Estimated Upgrade Time: 10 Minutes

Note:
We attempt to document every possible breaking change. Since some of these breaking changes are in obscure parts of the framework only a portion of these changes may actually affect your application. Want to save time? You can use Laravel Shift to help automate your application upgrades.

Updating Dependencies

Likelihood Of Impact: High

PHP 8.1.0 Required

Laravel now requires PHP 8.1.0 or greater.

Composer 2.2.0 Required

Laravel now requires Composer 2.2.0 or greater.

Composer Dependencies

You should update the following dependencies in your application's composer.json file:

If you are upgrading to Sanctum 3.x from the 2.x release series, please consult the Sanctum upgrade guide.

Furthermore, if you wish to use PHPUnit 10, you should delete the processUncoveredFiles attribute from the <coverage> section of your application's phpunit.xml configuration file. Then, update the following dependencies in your application's composer.json file:

Finally, examine any other third-party packages consumed by your application and verify you are using the proper version for Laravel 10 support.

Minimum Stability

You should update the minimum-stability setting in your application's composer.json file to stable. Or, since the default value of minimum-stability is stable, you may delete this setting from your application's composer.json file:

"minimum-stability": "stable",

Application

Public Path Binding

Likelihood Of Impact: Low

If your application is customizing its "public path" by binding path.public into the container, you should instead update your code to invoke the usePublicPath method offered by the Illuminate\Foundation\Application object:

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

Authorization

The registerPolicies Method

Likelihood Of Impact: Low

The registerPolicies method of the AuthServiceProvider is now invoked automatically by the framework. Therefore, you may remove the call to this method from the boot method of your application's AuthServiceProvider.

Cache

Redis Cache Tags

Likelihood Of Impact: Medium

Redis cache tag support has been rewritten for better performance and storage efficiency. In previous releases of Laravel, stale cache tags would accumulate in the cache when using Redis as your application's cache driver.

However, to properly prune stale cache tag entries, Laravel's new cache:prune-stale-tags Artisan command should be scheduled in your application's App\Console\Kernel class:

$schedule->command('cache:prune-stale-tags')->hourly();

Database

Database Expressions

Likelihood Of Impact: Medium

Database "expressions" (typically generated via DB::raw) have been rewritten in Laravel 10.x to offer additional functionality in the future. Notably, the grammar's raw string value must now be retrieved via the expression's getValue(Grammar $grammar) method. Casting an expression to a string using (string) is no longer supported.

Typically, this does not affect end-user applications; however, if your application is manually casting database expressions to strings using (string) or invoking the __toString method on the expression directly, you should update your code to invoke the getValue method instead:

use Illuminate\Support\Facades\DB;

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

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

Query Exception Constructor

Likelihood Of Impact: Very Low

The Illuminate\Database\QueryException constructor now accepts a string connection name as its first argument. If your application is manually throwing this exception, you should adjust your code accordingly.

ULID Columns

Likelihood Of Impact: Low

When migrations invoke the ulid method without any arguments, the column will now be named ulid. In previous releases of Laravel, invoking this method without any arguments created a column erroneously named uuid:

$table->ulid();

To explicitly specify a column name when invoking the ulid method, you may pass the column name to the method:

$table->ulid('ulid');

Eloquent

Model "Dates" Property

Likelihood Of Impact: Medium

The Eloquent model's deprecated $dates property has been removed. Your application should now use the $casts property:

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

Relation getBaseQuery Method

Likelihood Of Impact: Very Low

The getBaseQuery method on the Illuminate\Database\Eloquent\Relations\Relation class has been renamed to toBase.

Localization

The Language Directory

Likelihood Of Impact: None

Though not relevant to existing applications, the Laravel application skeleton no longer contains the lang directory by default. Instead, when writing new Laravel applications, it may be published using the lang:publish Artisan command:

php artisan lang:publish

Logging

Monolog 3

Likelihood Of Impact: Medium

Laravel's Monolog dependency has been updated to Monolog 3.x. If you are directly interacting with Monolog within your application, you should review Monolog's upgrade guide.

If you are using third-party logging services such as BugSnag or Rollbar, you may need to upgrade those third-party packages to a version that supports Monolog 3.x and Laravel 10.x.

Queues

The Bus::dispatchNow Method

Likelihood Of Impact: Low

The deprecated Bus::dispatchNow and dispatch_now methods have been removed. Instead, your application should use the Bus::dispatchSync and dispatch_sync methods, respectively.

Routing

Middleware Aliases

Likelihood Of Impact: Optional

In new Laravel applications, the $routeMiddleware property of the App\Http\Kernel class has been renamed to $middlewareAliases to better reflect its purpose. You are welcome to rename this property in your existing applications; however, it is not required.

Rate Limiter Return Values

Likelihood Of Impact: Low

When invoking the RateLimiter::attempt method, the value returned by the provided closure will now be returned by the method. If nothing or null is returned, the attempt method will return true:

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

$value; // ['example']

The Redirect::home Method

Likelihood Of Impact: Very Low

The deprecated Redirect::home method has been removed. Instead, your application should redirect to an explicitly named route:

return Redirect::route('home');

Testing

Service Mocking

Likelihood Of Impact: Medium

The deprecated MocksApplicationServices trait has been removed from the framework. This trait provided testing methods such as expectsEvents, expectsJobs, and expectsNotifications.

If your application uses these methods, we recommend you transition to Event::fake, Bus::fake, and Notification::fake, respectively. You can learn more about mocking via fakes in the corresponding documentation for the component you are attempting to fake.

Validation

Closure Validation Rule Messages

Likelihood Of Impact: Very Low

When writing closure based custom validation rules, invoking the $fail callback more than once will now append the messages to an array instead of overwriting the previous message. Typically, this will not affect your application.

In addition, the $fail callback now returns an object. If you were previously type-hinting the return type of your validation closure, this may require you to update your type-hint:

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

Miscellaneous

We also encourage you to view the changes in the laravel/laravel GitHub repository. While many of these changes are not required, you may wish to keep these files in sync with your application. Some of these changes will be covered in this upgrade guide, but others, such as changes to configuration files or comments, will not be.

You can easily view the changes with the GitHub comparison tool and choose which updates are important to you. However, many of the changes shown by the GitHub comparison tool are due to our organization's adoption of PHP native types. These changes are backwards compatible and the adoption of them during the migration to Laravel 10 is optional.