Upgrade Guide

    Estimated Upgrade Time: 10 Minutes

    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 2.2.0 or greater.

    Composer Dependencies

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

    • laravel/framework to ^10.0
    • laravel/sanctum to ^3.2
    • spatie/laravel-ignition to ^2.0

    Optionally, if you wish to use , 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:

    • nunomaduro/collision to ^7.0
    • phpunit/phpunit to ^10.0

    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:

    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:

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

    Authorization

    The registerPolicies Method

    Likelihood Of Impact: Low

    The 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.

    Redis Cache Tags

    Likelihood Of Impact: Medium

    Redis support has been rewritten for better performance and storage efficiency. In previously 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:

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

    Database

    Database Expressions

    Likelihood Of Impact: Medium

    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:

    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:

    1. $table->ulid();

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

    1. $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:

    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 Artisan command:

    1. php artisan lang:publish

    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

    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:

    1. $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:

    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.

    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:

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

    Miscellaneous

    We also encourage you to view the changes in the 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 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.