Upgrade Guide
High Impact Changes
Medium Impact Changes
Low Impact Changes
Upgrading To 10.0 From 9.x
Estimated Upgrade Time: 10 Minutes
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 Dependencies
You should update the following dependencies in your application's composer.json
file:
-
laravel/framework
to^10.0
-
spatie/laravel-ignition
to^2.0
Optionally, 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:
-
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
:
1"minimum-stability": "stable",
1"minimum-stability": "stable",
Cache
Redis Cache Tags
Likelihood Of Impact: Medium
Redis cache tag 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();
1$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:
1use Illuminate\Support\Facades\DB;23$expression = DB::raw('select 1');45$string = $expression->getValue(DB::connection()->getQueryGrammar());
1use Illuminate\Support\Facades\DB;23$expression = DB::raw('select 1');45$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 mainly 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();
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');
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:
1protected $casts = [2 'deployed_at' => 'datetime',3];
1protected $casts = [2 'deployed_at' => 'datetime',3];
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:
1php artisan lang:publish
1php artisan lang:publish
Logging
Monolog 3
Likelihood Of Impact: Low
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.
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
:
1$value = RateLimiter::attempt('key', 10, fn () => ['example'], 1);23$value; // ['example']
1$value = RateLimiter::attempt('key', 10, fn () => ['example'], 1);23$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:
1return Redirect::route('home');
1return 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 the complete mocking documentation.
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:
1public function rules()2{3 'name' => [4 function ($attribute, $value, $fail) {5 $fail('validation.translation.key')->translate();6 },7 ],8}
1public function rules()2{3 'name' => [4 function ($attribute, $value, $fail) {5 $fail('validation.translation.key')->translate();6 },7 ],8}
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.