- [Updating Dependencies](#updating-dependencies)
- [Updating Minimum Stability](#updating-minimum-stability)
- [Database Expressions](#database-expressions)
- [Model "Dates" Property](#model-dates-property)
- [Monolog 3](#monolog-3)
- [Redis Cache Tags](#redis-cache-tags)
- [Service Mocking](#service-mocking)
- [The Language Directory](#language-directory)
- [Closure Validation Rule Messages](#closure-validation-rule-messages)
- [Form Request `after` Method](#form-request-after-method)
- [Public Path Binding](#public-path-binding)
- [Query Exception Constructor](#query-exception-constructor)
- [Rate Limiter Return Values](#rate-limiter-return-values)
- [The `Redirect::home` Method](#redirect-home)
- [The `Bus::dispatchNow` Method](#dispatch-now)
- [The `registerPolicies` Method](#register-policies)
- [ULID Columns](#ulid-columns)
- `laravel/framework` to `^10.0`
- `laravel/sanctum` to `^3.2`
- `doctrine/dbal` to `^3.0`
- `spatie/laravel-ignition` to `^2.0`
- `laravel/passport` to `^11.0` ([Upgrade Guide](https://github.com/laravel/passport/blob/11.x/UPGRADE.md))
- `laravel/ui` to `^4.0`
If you are upgrading to Sanctum 3.x from the 2.x release series, please consult the [Sanctum upgrade guide](https://github.com/laravel/sanctum/blob/3.x/UPGRADE.md).
Furthermore, if you wish to use [PHPUnit 10](https://phpunit.de/announcements/phpunit-10.html), you should delete the `processUncoveredFiles` attribute from the `` 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`. Or, since the default value of `minimum-stability` is `stable`, you may delete this setting from your application's `composer.json` file:
```json
"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:
```php
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**
Usage of `Cache::tags()` is only recommended for applications using Memcached. If you are using Redis as your application's cache driver, you should consider moving to Memcached or upgrade your application to Laravel [12.30.0](https://github.com/laravel/framework/pull/57098).
### 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:
```php
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:
```php
protected $casts = [
'deployed_at' => 'datetime',
];
```
### 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:
```shell
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](https://github.com/Seldaek/monolog/blob/main/UPGRADE.md).
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.
#### The `dispatch()` Helper Return Value
**Likelihood Of Impact: Low**
Invoking `dispatch` with a class that does not implement `Illuminate\Contracts\Queue` would previously return the result of the class's `handle` method. However, this will now return an `Illuminate\Foundation\Bus\PendingBatch` instance. You may use `dispatch_sync()` to replicate the previous behavior.
### 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`:
```php
$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:
```php
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:
```php
public function rules()
{
'name' => [
function ($attribute, $value, $fail) {
$fail('validation.translation.key')->translate();
},
],
}
```
#### Validation Messages and Closure Rules
**Likelihood Of Impact: Very Low**
Previously, you could assign a failure message to a different key by providing an array to the `$fail` callback injected into Closure based validation rules. However, you should now provide the key as the first argument and the failure message as the second argument:
```php
Validator::make([
'foo' => 'string',
'bar' => [function ($attribute, $value, $fail) {
$fail('foo', 'Something went wrong!');
}],
]);
```
#### Form Request After Method
**Likelihood Of Impact: Very Low**
Within form requests, the `after` method is now [reserved by Laravel](https://github.com/laravel/framework/pull/46757). If your form requests define an `after` method, the method should be renamed or modified to utilize the new "after validation" feature of Laravel's form requests.
### Miscellaneous
We also encourage you to view the changes in the `laravel/laravel` [GitHub repository](https://github.com/laravel/laravel). 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](https://github.com/laravel/laravel/compare/9.x...10.x) 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.
# Upgrade Guide
- [Upgrading To 11.0 From 10.x](#upgrade-11.0)
## High Impact Changes
- [Updating Dependencies](#updating-dependencies)
- [Application Structure](#application-structure)
- [Floating-Point Types](#floating-point-types)
- [Modifying Columns](#modifying-columns)
- [SQLite Minimum Version](#sqlite-minimum-version)
- [Updating Sanctum](#updating-sanctum)
## Medium Impact Changes
- [Carbon 3](#carbon-3)
- [Password Rehashing](#password-rehashing)
- [Per-Second Rate Limiting](#per-second-rate-limiting)
- [Spatie Once Package](#spatie-once-package)
## Low Impact Changes
- [Doctrine DBAL Removal](#doctrine-dbal-removal)
- [Eloquent Model `casts` Method](#eloquent-model-casts-method)
- [Spatial Types](#spatial-types)
- [The `Enumerable` Contract](#the-enumerable-contract)
- [The `UserProvider` Contract](#the-user-provider-contract)
- [The `Authenticatable` Contract](#the-authenticatable-contract)
## Upgrading To 11.0 From 10.x
#### Estimated Upgrade Time: 15 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](https://laravelshift.com/) to help automate your application upgrades.
### Updating Dependencies
**Likelihood Of Impact: High**
#### PHP 8.2.0 Required
Laravel now requires PHP 8.2.0 or greater.
#### curl 7.34.0 Required
Laravel's HTTP client now requires curl 7.34.0 or greater.
#### Composer Dependencies
You should update the following dependencies in your application's `composer.json` file:
- `laravel/framework` to `^11.0`
- `nunomaduro/collision` to `^8.1`
- `laravel/breeze` to `^2.0` (If installed)
- `laravel/cashier` to `^15.0` (If installed)
- `laravel/dusk` to `^8.0` (If installed)
- `laravel/jetstream` to `^5.0` (If installed)
- `laravel/octane` to `^2.3` (If installed)
- `laravel/passport` to `^12.0` (If installed)
- `laravel/sanctum` to `^4.0` (If installed)
- `laravel/scout` to `^10.0` (If installed)
- `laravel/spark-stripe` to `^5.0` (If installed)
- `laravel/telescope` to `^5.0` (If installed)
- `livewire/livewire` to `^3.4` (If installed)
- `inertiajs/inertia-laravel` to `^1.0` (If installed)
If your application is using Laravel Cashier Stripe, Passport, Sanctum, Spark Stripe, or Telescope, you will need to publish their migrations to your application. Cashier Stripe, Passport, Sanctum, Spark Stripe, and Telescope **no longer automatically load migrations from their own migrations** directory. Therefore, you should run the following command to publish their migrations to your application:
```bash
php artisan vendor:publish --tag=cashier-migrations
php artisan vendor:publish --tag=passport-migrations
php artisan vendor:publish --tag=sanctum-migrations
php artisan vendor:publish --tag=spark-migrations
php artisan vendor:publish --tag=telescope-migrations
```
In addition, you should review the upgrade guides for each of these packages to ensure you are aware of any additional breaking changes:
- [Laravel Cashier Stripe](#cashier-stripe)
- [Laravel Passport](#passport)
- [Laravel Sanctum](#sanctum)
- [Laravel Spark Stripe](#spark-stripe)
- [Laravel Telescope](#telescope)
If you have manually installed the Laravel installer, you should update the installer via Composer:
```bash
composer global require laravel/installer:^5.6
```
Finally, you may remove the `doctrine/dbal` Composer dependency if you have previously added it to your application, as Laravel is no longer dependent on this package.
### Application Structure
Laravel 11 introduces a new default application structure with fewer default files. Namely, new Laravel applications contain fewer service providers, middleware, and configuration files.
However, we do **not recommend** that Laravel 10 applications upgrading to Laravel 11 attempt to migrate their application structure, as Laravel 11 has been carefully tuned to also support the Laravel 10 application structure.
### Authentication
#### Password Rehashing
**Likelihood Of Impact: Low**
Laravel 11 will automatically rehash your user's passwords during authentication if your hashing algorithm's "work factor" has been updated since the password was last hashed.
Typically, this should not disrupt your application; however, if your `User` model's "password" field has a name other than `password`, you should specify the field's name via the model's `authPasswordName` property:
protected $authPasswordName = 'custom_password_field';
Alternatively, you may disable password rehashing by adding the `rehash_on_login` option to your application's `config/hashing.php` configuration file:
'rehash_on_login' => false,
#### The `UserProvider` Contract
**Likelihood Of Impact: Low**
The `Illuminate\Contracts\Auth\UserProvider` contract has received a new `rehashPasswordIfRequired` method. This method is responsible for re-hashing and storing the user's password in storage when the application's hashing algorithm work factor has changed.
If your application or package defines a class that implements this interface, you should add the new `rehashPasswordIfRequired` method to your implementation. A reference implementation can be found within the `Illuminate\Auth\EloquentUserProvider` class:
```php
public function rehashPasswordIfRequired(Authenticatable $user, array $credentials, bool $force = false);
```
#### The `Authenticatable` Contract
**Likelihood Of Impact: Low**
The `Illuminate\Contracts\Auth\Authenticatable` contract has received a new `getAuthPasswordName` method. This method is responsible for returning the name of your authenticatable entity's password column.
If your application or package defines a class that implements this interface, you should add the new `getAuthPasswordName` method to your implementation:
```php
public function getAuthPasswordName()
{
return 'password';
}
```
The default `User` model included with Laravel receives this method automatically since the method is included within the `Illuminate\Auth\Authenticatable` trait.
#### The `AuthenticationException` Class
**Likelihood Of Impact: Very Low**
The `redirectTo` method of the `Illuminate\Auth\AuthenticationException` class now requires an `Illuminate\Http\Request` instance as its first argument. If you are manually catching this exception and calling the `redirectTo` method, you should update your code accordingly:
```php
if ($e instanceof AuthenticationException) {
$path = $e->redirectTo($request);
}
```
#### Email Verification Notification on Registration
**Likelihood Of Impact: Very Low**
The `SendEmailVerificationNotification` listener is now automatically registered for the `Registered` event if it is not already registered by your application's `EventServiceProvider`. If your application's `EventServiceProvider` does not register this listener and you do not want Laravel to automatically register it for you, you should define an empty `configureEmailVerification` method in your application's `EventServiceProvider`:
```php
protected function configureEmailVerification()
{
// ...
}
```
### Cache
#### Cache Key Prefixes
**Likelihood Of Impact: Very Low**
Previously, if a cache key prefix was defined for the DynamoDB, Memcached, or Redis cache stores, Laravel would append a `:` to the prefix. In Laravel 11, the cache key prefix does not receive the `:` suffix. If you would like to maintain the previous prefixing behavior, you can manually add the `:` suffix to your cache key prefix.
### Collections
#### The `Enumerable` Contract
**Likelihood Of Impact: Low**
The `dump` method of the `Illuminate\Support\Enumerable` contract has been updated to accept a variadic `...$args` argument. If you are implementing this interface you should update your implementation accordingly:
```php
public function dump(...$args);
```
### Database
#### SQLite 3.26.0+
**Likelihood Of Impact: High**
If your application is utilizing an SQLite database, SQLite 3.26.0 or greater is required.
#### Eloquent Model `casts` Method
**Likelihood Of Impact: Low**
The base Eloquent model class now defines a `casts` method in order to support the definition of attribute casts. If one of your application's models is defining a `casts` relationship, it may conflict with the `casts` method now present on the base Eloquent model class.
#### Modifying Columns
**Likelihood Of Impact: High**
When modifying a column, you must now explicitly include all the modifiers you want to keep on the column definition after it is changed. Any missing attributes will be dropped. For example, to retain the `unsigned`, `default`, and `comment` attributes, you must call each modifier explicitly when changing the column, even if those attributes have been assigned to the column by a previous migration.
For example, imagine you have a migration that creates a `votes` column with the `unsigned`, `default`, and `comment` attributes:
```php
Schema::create('users', function (Blueprint $table) {
$table->integer('votes')->unsigned()->default(1)->comment('The vote count');
});
```
Later, you write a migration that changes the column to be `nullable` as well:
```php
Schema::table('users', function (Blueprint $table) {
$table->integer('votes')->nullable()->change();
});
```
In Laravel 10, this migration would retain the `unsigned`, `default`, and `comment` attributes on the column. However, in Laravel 11, the migration must now also include all of the attributes that were previously defined on the column. Otherwise, they will be dropped:
```php
Schema::table('users', function (Blueprint $table) {
$table->integer('votes')
->unsigned()
->default(1)
->comment('The vote count')
->nullable()
->change();
});
```
The `change` method does not change the indexes of the column. Therefore, you may use index modifiers to explicitly add or drop an index when modifying the column:
```php
// Add an index...
$table->bigIncrements('id')->primary()->change();
// Drop an index...
$table->char('postal_code', 10)->unique(false)->change();
```
If you do not want to update all of the existing "change" migrations in your application to retain the column's existing attributes, you may simply [squash your migrations](/docs/{{version}}/migrations#squashing-migrations):
```bash
php artisan schema:dump
```
Once your migrations have been squashed, Laravel will "migrate" the database using your application's schema file before running any pending migrations.
#### Floating-Point Types
**Likelihood Of Impact: High**
The `double` and `float` migration column types have been rewritten to be consistent across all databases.
The `double` column type now creates a `DOUBLE` equivalent column without total digits and places (digits after decimal point), which is the standard SQL syntax. Therefore, you may remove the arguments for `$total` and `$places`:
```php
$table->double('amount');
```
The `float` column type now creates a `FLOAT` equivalent column without total digits and places (digits after decimal point), but with an optional `$precision` specification to determine storage size as a 4-byte single-precision column or an 8-byte double-precision column. Therefore, you may remove the arguments for `$total` and `$places` and specify the optional `$precision` to your desired value and according to your database's documentation:
```php
$table->float('amount', precision: 53);
```
The `unsignedDecimal`, `unsignedDouble`, and `unsignedFloat` methods have been removed, as the unsigned modifier for these column types has been deprecated by MySQL, and was never standardized on other database systems. However, if you wish to continue using the deprecated unsigned attribute for these column types, you may chain the `unsigned` method onto the column's definition:
```php
$table->decimal('amount', total: 8, places: 2)->unsigned();
$table->double('amount')->unsigned();
$table->float('amount', precision: 53)->unsigned();
```
#### Dedicated MariaDB Driver
**Likelihood Of Impact: Very Low**
Instead of always utilizing the MySQL driver when connecting to MariaDB databases, Laravel 11 adds a dedicated database driver for MariaDB.
If your application connects to a MariaDB database, you may update the connection configuration to the new `mariadb` driver to benefit from MariaDB specific features in the future:
'driver' => 'mariadb',
'url' => env('DB_URL'),
'host' => env('DB_HOST', '127.0.0.1'),
'port' => env('DB_PORT', '3306'),
// ...
Currently, the new MariaDB driver behaves like the current MySQL driver with one exception: the `uuid` schema builder method creates native UUID columns instead of `char(36)` columns.
If your existing migrations utilize the `uuid` schema builder method and you choose to use the new `mariadb` database driver, you should update your migration's invocations of the `uuid` method to `char` to avoid breaking changes or unexpected behavior:
```php
Schema::table('users', function (Blueprint $table) {
$table->char('uuid', 36);
// ...
});
```
#### Spatial Types
**Likelihood Of Impact: Low**
The spatial column types of database migrations have been rewritten to be consistent across all databases. Therefore, you may remove `point`, `lineString`, `polygon`, `geometryCollection`, `multiPoint`, `multiLineString`, `multiPolygon`, and `multiPolygonZ` methods from your migrations and use `geometry` or `geography` methods instead:
```php
$table->geometry('shapes');
$table->geography('coordinates');
```
To explicitly restrict the type or the spatial reference system identifier for values stored in the column on MySQL, MariaDB, and PostgreSQL, you may pass the `subtype` and `srid` to the method:
```php
$table->geometry('dimension', subtype: 'polygon', srid: 0);
$table->geography('latitude', subtype: 'point', srid: 4326);
```
The `isGeometry` and `projection` column modifiers of the PostgreSQL grammar have been removed accordingly.
#### Doctrine DBAL Removal
**Likelihood Of Impact: Low**
The following list of Doctrine DBAL related classes and methods have been removed. Laravel is no longer dependent on this package and registering custom Doctrines types is no longer necessary for the proper creation and alteration of various column types that previously required custom types:
- `Illuminate\Database\Schema\Builder::$alwaysUsesNativeSchemaOperationsIfPossible` class property
- `Illuminate\Database\Schema\Builder::useNativeSchemaOperationsIfPossible()` method
- `Illuminate\Database\Connection::usingNativeSchemaOperations()` method
- `Illuminate\Database\Connection::isDoctrineAvailable()` method
- `Illuminate\Database\Connection::getDoctrineConnection()` method
- `Illuminate\Database\Connection::getDoctrineSchemaManager()` method
- `Illuminate\Database\Connection::getDoctrineColumn()` method
- `Illuminate\Database\Connection::registerDoctrineType()` method
- `Illuminate\Database\DatabaseManager::registerDoctrineType()` method
- `Illuminate\Database\PDO` directory
- `Illuminate\Database\DBAL\TimestampType` class
- `Illuminate\Database\Schema\Grammars\ChangeColumn` class
- `Illuminate\Database\Schema\Grammars\RenameColumn` class
- `Illuminate\Database\Schema\Grammars\Grammar::getDoctrineTableDiff()` method
In addition, registering custom Doctrine types via `dbal.types` in your application's `database` configuration file is no longer required.
If you were previously using Doctrine DBAL to inspect your database and its associated tables, you may use Laravel's new native schema methods (`Schema::getTables()`, `Schema::getColumns()`, `Schema::getIndexes()`, `Schema::getForeignKeys()`, etc.) instead.
#### Deprecated Schema Methods
**Likelihood Of Impact: Very Low**
The deprecated, Doctrine based `Schema::getAllTables()`, `Schema::getAllViews()`, and `Schema::getAllTypes()` methods have been removed in favor of new Laravel native `Schema::getTables()`, `Schema::getViews()`, and `Schema::getTypes()` methods.
When using PostgreSQL and SQL Server, none of the new schema methods will accept a three-part reference (e.g. `database.schema.table`). Therefore, you should use `connection()` to declare the database instead:
```php
Schema::connection('database')->hasTable('schema.table');
```
#### Schema Builder `getColumnType()` Method
**Likelihood Of Impact: Very Low**
The `Schema::getColumnType()` method now always returns actual type of the given column, not the Doctrine DBAL equivalent type.
#### Database Connection Interface
**Likelihood Of Impact: Very Low**
The `Illuminate\Database\ConnectionInterface` interface has received a new `scalar` method. If you are defining your own implementation of this interface, you should add the `scalar` method to your implementation:
```php
public function scalar($query, $bindings = [], $useReadPdo = true);
```
### Dates
#### Carbon 3
**Likelihood Of Impact: Medium**
Laravel 11 supports both Carbon 2 and Carbon 3. Carbon is a date manipulation library utilized extensively by Laravel and packages throughout the ecosystem. If you upgrade to Carbon 3, be aware that `diffIn*` methods now return floating-point numbers and may return negative values to indicate time direction, which is a significant change from Carbon 2. Review Carbon's [change log](https://github.com/briannesbitt/Carbon/releases/tag/3.0.0) and [documentation](https://carbon.nesbot.com/guide/getting-started/migration.html) for detailed information on how to handle these and other changes.
### Mail
#### The `Mailer` Contract
**Likelihood Of Impact: Very Low**
The `Illuminate\Contracts\Mail\Mailer` contract has received a new `sendNow` method. If your application or package is manually implementing this contract, you should add the new `sendNow` method to your implementation:
```php
public function sendNow($mailable, array $data = [], $callback = null);
```
### Packages
#### Publishing Service Providers to the Application
**Likelihood Of Impact: Very Low**
If you have written a Laravel package that manually publishes a service provider to the application's `app/Providers` directory and manually modifies the application's `config/app.php` configuration file to register the service provider, you should update your package to utilize the new `ServiceProvider::addProviderToBootstrapFile` method.
The `addProviderToBootstrapFile` method will automatically add the service provider you have published to the application's `bootstrap/providers.php` file, since the `providers` array does not exist within the `config/app.php` configuration file in new Laravel 11 applications.
```php
use Illuminate\Support\ServiceProvider;
ServiceProvider::addProviderToBootstrapFile(Provider::class);
```
### Queues
#### The `BatchRepository` Interface
**Likelihood Of Impact: Very Low**
The `Illuminate\Bus\BatchRepository` interface has received a new `rollBack` method. If you are implementing this interface within your own package or application, you should add this method to your implementation:
```php
public function rollBack();
```
#### Synchronous Jobs in Database Transactions
**Likelihood Of Impact: Very Low**
Previously, synchronous jobs (jobs using the `sync` queue driver) would execute immediately, regardless of whether the `after_commit` configuration option of the queue connection was set to `true` or the `afterCommit` method was invoked on the job.
In Laravel 11, synchronous queue jobs will now respect the "after commit" configuration of the queue connection or job.
### Rate Limiting
#### Per-Second Rate Limiting
**Likelihood Of Impact: Medium**
Laravel 11 supports per-second rate limiting instead of being limited to per-minute granularity. There are a variety of potential breaking changes you should be aware of related to this change.
The `GlobalLimit` class constructor now accepts seconds instead of minutes. This class is not documented and would not typically be used by your application:
```php
new GlobalLimit($attempts, 2 * 60);
```
The `Limit` class constructor now accepts seconds instead of minutes. All documented usages of this class are limited to static constructors such as `Limit::perMinute` and `Limit::perSecond`. However, if you are instantiating this class manually, you should update your application to provide seconds to the class's constructor:
```php
new Limit($key, $attempts, 2 * 60);
```
The `Limit` class's `decayMinutes` property has been renamed to `decaySeconds` and now contains seconds instead of minutes.
The `Illuminate\Queue\Middleware\ThrottlesExceptions` and `Illuminate\Queue\Middleware\ThrottlesExceptionsWithRedis` class constructors now accept seconds instead of minutes:
```php
new ThrottlesExceptions($attempts, 2 * 60);
new ThrottlesExceptionsWithRedis($attempts, 2 * 60);
```
### Cashier Stripe
#### Updating Cashier Stripe
**Likelihood Of Impact: High**
Laravel 11 no longer supports Cashier Stripe 14.x. Therefore, you should update your application's Laravel Cashier Stripe dependency to `^15.0` in your `composer.json` file.
Cashier Stripe 15.0 no longer automatically loads migrations from its own migrations directory. Instead, you should run the following command to publish Cashier Stripe's migrations to your application:
```shell
php artisan vendor:publish --tag=cashier-migrations
```
Please review the complete [Cashier Stripe upgrade guide](https://github.com/laravel/cashier-stripe/blob/15.x/UPGRADE.md) for additional breaking changes.
### Spark (Stripe)
#### Updating Spark Stripe
**Likelihood Of Impact: High**
Laravel 11 no longer supports Laravel Spark Stripe 4.x. Therefore, you should update your application's Laravel Spark Stripe dependency to `^5.0` in your `composer.json` file.
Spark Stripe 5.0 no longer automatically loads migrations from its own migrations directory. Instead, you should run the following command to publish Spark Stripe's migrations to your application:
```shell
php artisan vendor:publish --tag=spark-migrations
```
Please review the complete [Spark Stripe upgrade guide](https://spark.laravel.com/docs/spark-stripe/upgrade.html) for additional breaking changes.
### Passport
#### Updating Passport
**Likelihood Of Impact: High**
Laravel 11 no longer supports Laravel Passport 11.x. Therefore, you should update your application's Laravel Passport dependency to `^12.0` in your `composer.json` file.
Passport 12.0 no longer automatically loads migrations from its own migrations directory. Instead, you should run the following command to publish Passport's migrations to your application:
```shell
php artisan vendor:publish --tag=passport-migrations
```
In addition, the password grant type is disabled by default. You may enable it by invoking the `enablePasswordGrant` method in the `boot` method of your application's `AppServiceProvider`:
public function boot(): void
{
Passport::enablePasswordGrant();
}
### Sanctum
#### Updating Sanctum
**Likelihood Of Impact: High**
Laravel 11 no longer supports Laravel Sanctum 3.x. Therefore, you should update your application's Laravel Sanctum dependency to `^4.0` in your `composer.json` file.
Sanctum 4.0 no longer automatically loads migrations from its own migrations directory. Instead, you should run the following command to publish Sanctum's migrations to your application:
```shell
php artisan vendor:publish --tag=sanctum-migrations
```
Then, in your application's `config/sanctum.php` configuration file, you should update the references to the `authenticate_session`, `encrypt_cookies`, and `validate_csrf_token` middleware to the following:
'middleware' => [
'authenticate_session' => Laravel\Sanctum\Http\Middleware\AuthenticateSession::class,
'encrypt_cookies' => Illuminate\Cookie\Middleware\EncryptCookies::class,
'validate_csrf_token' => Illuminate\Foundation\Http\Middleware\ValidateCsrfToken::class,
],
### Telescope
#### Updating Telescope
**Likelihood Of Impact: High**
Laravel 11 no longer supports Laravel Telescope 4.x. Therefore, you should update your application's Laravel Telescope dependency to `^5.0` in your `composer.json` file.
Telescope 5.0 no longer automatically loads migrations from its own migrations directory. Instead, you should run the following command to publish Telescope's migrations to your application:
```shell
php artisan vendor:publish --tag=telescope-migrations
```
### Spatie Once Package
**Likelihood Of Impact: Medium**
Laravel 11 now provides its own [`once` function](/docs/{{version}}/helpers#method-once) to ensure that a given closure is only executed once. Therefore, if your application has a dependency on the `spatie/once` package, you should remove it from your application's `composer.json` file to avoid conflicts.
### Miscellaneous
We also encourage you to view the changes in the `laravel/laravel` [GitHub repository](https://github.com/laravel/laravel). 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](https://github.com/laravel/laravel/compare/10.x...11.x) and choose which updates are important to you.
# Upgrade Guide
- [Upgrading To 12.0 From 11.x](#upgrade-12.0)
## High Impact Changes
- [Updating Dependencies](#updating-dependencies)
- [Updating the Laravel Installer](#updating-the-laravel-installer)
## Medium Impact Changes
- [Models and UUIDv7](#models-and-uuidv7)
## Low Impact Changes
- [Carbon 3](#carbon-3)
- [Concurrency Result Index Mapping](#concurrency-result-index-mapping)
- [Container Class Dependency Resolution](#container-class-dependency-resolution)
- [Image Validation Now Excludes SVGs](#image-validation)
- [Local Filesystem Disk Default Root Path](#local-filesystem-disk-default-root-path)
- [Multi-Schema Database Inspecting](#multi-schema-database-inspecting)
- [Nested Array Request Merging](#nested-array-request-merging)
## Upgrading To 12.0 From 11.x
#### Estimated Upgrade Time: 5 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](https://laravelshift.com/) to help automate your application upgrades.
### Updating Dependencies
**Likelihood Of Impact: High**
You should update the following dependencies in your application's `composer.json` file:
- `laravel/framework` to `^12.0`
- `phpunit/phpunit` to `^11.0`
- `pestphp/pest` to `^3.0`
#### Carbon 3
**Likelihood Of Impact: Low**
Support for Carbon 2.x has been removed. All Laravel 12 applications now require [Carbon 3.x](https://carbon.nesbot.com/guide/getting-started/migration.html).
### Updating the Laravel Installer
If you are using the Laravel installer CLI tool to create new Laravel applications, you should update your installer installation to be compatible with Laravel 12.x and the [new Laravel starter kits](https://laravel.com/starter-kits). If you installed the Laravel installer via `composer global require`, you may update the installer using `composer global update`:
```shell
composer global update laravel/installer
```
If you originally installed PHP and Laravel via `php.new`, you may simply re-run the `php.new` installation commands for your operating system to install the latest version of PHP and the Laravel installer:
```shell tab=macOS
/bin/bash -c "$(curl -fsSL https://php.new/install/mac/8.4)"
```
```shell tab=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'))
```
```shell tab=Linux
/bin/bash -c "$(curl -fsSL https://php.new/install/linux/8.4)"
```
Or, if you are using [Laravel Herd's](https://herd.laravel.com) bundled copy of the Laravel installer, you should update your Herd installation to the latest release.
### Authentication
#### Updated `DatabaseTokenRepository` Constructor Signature
**Likelihood Of Impact: Very Low**
The constructor of the `Illuminate\Auth\Passwords\DatabaseTokenRepository` class now expects the `$expires` parameter to be given in seconds, rather than minutes.
### Concurrency
#### Concurrency Result Index Mapping
**Likelihood Of Impact: Low**
When invoking the `Concurrency::run` method with an associative array, the results of the concurrent operations are now returned with their associated keys:
```php
$result = Concurrency::run([
'task-1' => fn () => 1 + 1,
'task-2' => fn () => 2 + 2,
]);
// ['task-1' => 2, 'task-2' => 4]
```
### Container
#### Container Class Dependency Resolution
**Likelihood Of Impact: Low**
The dependency injection container now respects the default value of class properties when resolving a class instance. If you were previously relying on the container to resolve a class instance without the default value, you may need to adjust your application to account for this new behavior:
```php
class Example
{
public function __construct(public ?Carbon $date = null) {}
}
$example = resolve(Example::class);
// <= 11.x
$example->date instanceof Carbon;
// >= 12.x
$example->date === null;
```
### Database
#### Multi-Schema Database Inspecting
**Likelihood Of Impact: Low**
The `Schema::getTables()`, `Schema::getViews()`, and `Schema::getTypes()` methods now include the results from all schemas by default. You may pass the `schema` argument to retrieve the result for the given schema only:
```php
// All tables on all schemas...
$tables = Schema::getTables();
// All tables on the 'main' schema...
$tables = Schema::getTables(schema: 'main');
// All tables on the 'main' and 'blog' schemas...
$tables = Schema::getTables(schema: ['main', 'blog']);
```
The `Schema::getTableListing()` method now returns schema-qualified table names by default. You may pass the `schemaQualified` argument to change the behavior as desired:
```php
$tables = Schema::getTableListing();
// ['main.migrations', 'main.users', 'blog.posts']
$tables = Schema::getTableListing(schema: 'main');
// ['main.migrations', 'main.users']
$tables = Schema::getTableListing(schema: 'main', schemaQualified: false);
// ['migrations', 'users']
```
The `db:table` and `db:show` commands now output the results of all schemas on MySQL, MariaDB, and SQLite, just like PostgreSQL and SQL Server.
#### Database Constructor Signature Changes
**Likelihood Of Impact: Very Low**
In Laravel 12, several low-level database classes now require an `Illuminate\Database\Connection` instance to be provided via their constructors.
**These changes are primarily applicable to database package maintainers - it is extremely unlikely any of these changes affect normal application development.**
`Illuminate\Database\Schema\Blueprint`
The constructor of the `Illuminate\Database\Schema\Blueprint` class now expects a `Connection` instance as its first argument. This primarily affects applications or packages that manually instantiate `Blueprint` instances.
`Illuminate\Database\Grammar`
The constructor of the `Illuminate\Database\Grammar` class also now requires a `Connection` instance. In previous versions, the connection was assigned after construction using the `setConnection()` method. This method has been removed in Laravel 12:
```php
// Laravel <= 11.x
$grammar = new MySqlGrammar;
$grammar->setConnection($connection);
// Laravel >= 12.x
$grammar = new MySqlGrammar($connection);
````
In addition, the following APIs have been removed or deprecated:
- The `Blueprint::getPrefix()` method is deprecated.
- The `Connection::withTablePrefix()` method has been removed.
- The `Grammar::getTablePrefix()` and `setTablePrefix()` methods are deprecated.
- The `Grammar::setConnection()` method has been removed.
When working with table prefixes, you should now retrieve them directly from the database connection:
```php
$prefix = $connection->getTablePrefix();
```
If you maintain custom database drivers, schema builders, or grammar implementations, you should review their constructors and ensure a `Connection` instance is provided.
### Eloquent
#### Models and UUIDv7
**Likelihood Of Impact: Medium**
The `HasUuids` trait now returns UUIDs that are compatible with version 7 of the UUID spec (ordered UUIDs). If you would like to continue using ordered UUIDv4 strings for your model's IDs, you should now use the `HasVersion4Uuids` trait:
```php
use Illuminate\Database\Eloquent\Concerns\HasUuids; // [tl! remove]
use Illuminate\Database\Eloquent\Concerns\HasVersion4Uuids as HasUuids; // [tl! add]
```
The `HasVersion7Uuids` trait has been removed. If you were previously using this trait, you should use the `HasUuids` trait instead, which now provides the same behavior.
### Requests
#### Nested Array Request Merging
**Likelihood Of Impact: Low**
The `$request->mergeIfMissing()` method now allows merging nested array data using "dot" notation. If you were previously relying on this method to create a top-level array key containing the "dot" notation version of the key, you may need to adjust your application to account for this new behavior:
```php
$request->mergeIfMissing([
'user.last_name' => 'Otwell',
]);
```
### Routing
#### Route Precedence
**Likelihood Of Impact: Low**
The routing behavior when multiple routes have the same name has been unified between cached and uncached routing. This means that uncached routing now matches the first route registered with a given name instead of the last one.
### Storage
#### Local Filesystem Disk Default Root Path
**Likelihood Of Impact: Low**
If your application does not explicitly define a `local` disk in your filesystems configuration, Laravel will now default the local disk's root to `storage/app/private`. In previous releases, this defaulted to `storage/app`. As a result, calls to `Storage::disk('local')` will read from and write to `storage/app/private` unless otherwise configured. To restore the previous behavior, you may define the `local` disk manually and set the desired root path.
### Validation
#### Image Validation Now Excludes SVGs
**Likelihood Of Impact: Low**
The `image` validation rule no longer allows SVG images by default. If you would like to allow SVGs when using the `image` rule, you must explicitly allow them:
```php
use Illuminate\Validation\Rules\File;
'photo' => 'required|image:allow_svg'
// Or...
'photo' => ['required', File::image(allowSvg: true)],
```
### Miscellaneous
We also encourage you to view the changes in the `laravel/laravel` [GitHub repository](https://github.com/laravel/laravel). 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](https://github.com/laravel/laravel/compare/11.x...12.x) and choose which updates are important to you.
# Upgrade Guide
- [Upgrading To 13.0 From 12.x](#upgrade-13.0)
- [Upgrading Using AI](#upgrading-using-ai)
## High Impact Changes
- [Updating Dependencies](#updating-dependencies)
- [Updating the Laravel Installer](#updating-the-laravel-installer)
- [Request Forgery Protection](#request-forgery-protection)
## Medium Impact Changes
- [Cache `serializable_classes` Configuration](#cache-serializable_classes-configuration)
- [Database `upsert` With MySQL or MariaDB](#database-upsert-mariadb-mysql)
## Low Impact Changes
- [Cache Prefixes and Session Cookie Names](#cache-prefixes-and-session-cookie-names)
- [Collection Model Serialization Restores Eager-Loaded Relations](#collection-model-serialization-restores-eager-loaded-relations)
- [`Container::call` and Nullable Class Defaults](#containercall-and-nullable-class-defaults)
- [Domain Route Registration Precedence](#domain-route-registration-precedence)
- [`JobAttempted` Event Exception Payload](#jobattempted-event-exception-payload)
- [Manager `extend` Callback Binding](#manager-extend-callback-binding)
- [MySQL `DELETE` Queries With `JOIN`, `ORDER BY`, and `LIMIT`](#mysql-delete-queries-with-join-order-by-and-limit)
- [Pagination Bootstrap View Names](#pagination-bootstrap-view-names)
- [Polymorphic Pivot Table Name Generation](#polymorphic-pivot-table-name-generation)
- [`QueueBusy` Event Property Rename](#queuebusy-event-property-rename)
- [Session `serialization` Configuration](#session-serialization-configuration)
- [`Str` Factories Reset Between Tests](#str-factories-reset-between-tests)
## Upgrading To 13.0 From 12.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. To save time, you may use [Shift](https://laravelshift.com). Shift is a community-maintained service that automates Laravel upgrades.
### Upgrading Using AI
You can automate your upgrade using [Laravel Boost](https://github.com/laravel/boost). Boost is a first-party MCP server that provides your AI assistant with guided upgrade prompts — once installed in any Laravel 12 application, use the `/upgrade-laravel-v13` slash command in Claude Code, Cursor, OpenCode, Gemini, or VS Code to begin the upgrade to Laravel 13. This command requires Laravel Boost `^2.0`.
### Updating Dependencies
**Likelihood Of Impact: High**
You should update the following dependencies in your application's `composer.json` file:
- `laravel/framework` to `^13.0`
- `laravel/boost` to `^2.0`
- `laravel/tinker` to `^3.0`
- `phpunit/phpunit` to `^12.0`
- `pestphp/pest` to `^4.0`
### Updating the Laravel Installer
If you are using the Laravel installer CLI tool to create new Laravel applications, you should update your installer installation for Laravel 13.x compatibility.
If you installed the Laravel installer via `composer global require`, you may update the installer using `composer global update`:
```shell
composer global update laravel/installer
```
Or, if you are using [Laravel Herd's](https://herd.laravel.com) bundled copy of the Laravel installer, you should update your Herd installation to the latest release.
### Cache
#### Cache Prefixes and Session Cookie Names
**Likelihood Of Impact: Low**
Laravel's default cache and Redis key prefixes now use hyphenated suffixes.
In most applications, this change will not apply because application-level configuration files already define these values. This primarily affects applications that rely on framework-level fallback configuration when corresponding application config values are not present.
If your application relies on these generated defaults, cache keys and session cookie names may change after upgrading:
```php
// Laravel <= 12.x
Str::slug((string) env('APP_NAME', 'laravel'), '_').'_cache_';
Str::slug((string) env('APP_NAME', 'laravel'), '_').'_database_';
Str::slug((string) env('APP_NAME', 'laravel'), '_').'_session';
// Laravel >= 13.x
Str::slug((string) env('APP_NAME', 'laravel')).'-cache-';
Str::slug((string) env('APP_NAME', 'laravel')).'-database-';
Str::slug((string) env('APP_NAME', 'laravel')).'-session';
```
To retain previous behavior, explicitly configure `CACHE_PREFIX`, `REDIS_PREFIX`, and `SESSION_COOKIE` in your environment.
#### `Store` and `Repository` Contracts: `touch`
**Likelihood Of Impact: Very Low**
The cache contracts now include a `touch` method for extending item TTLs. If you maintain custom cache store implementations, you should add this method:
```php
// Illuminate\Contracts\Cache\Store
public function touch($key, $seconds);
```
#### Cache `serializable_classes` Configuration
**Likelihood Of Impact: Medium**
The default application `cache` configuration now includes a `serializable_classes` option set to `false`. This hardens cache unserialization behavior to help prevent PHP deserialization gadget chain attacks if your application's `APP_KEY` is leaked. If your application intentionally stores PHP objects in cache, you should explicitly list the classes that may be unserialized:
```php
'serializable_classes' => [
App\Data\CachedDashboardStats::class,
App\Support\CachedPricingSnapshot::class,
],
```
If your application previously relied on unserializing arbitrary cached objects, you will need to migrate that usage to explicit class allow-lists or to non-object cache payloads (such as arrays).
### Container
#### `Container::call` and Nullable Class Defaults
**Likelihood Of Impact: Low**
`Container::call` now respects nullable class parameter defaults when no binding exists, matching constructor injection behavior introduced in Laravel 12:
```php
$container->call(function (?Carbon $date = null) {
return $date;
});
// Laravel <= 12.x: Carbon instance
// Laravel >= 13.x: null
```
If your method-call injection logic depended on the previous behavior, you may need to update it.
### Contracts
#### `Dispatcher` Contract: `dispatchAfterResponse`
**Likelihood Of Impact: Very Low**
The `Illuminate\Contracts\Bus\Dispatcher` contract now includes the `dispatchAfterResponse($command, $handler = null)` method.
If you maintain a custom dispatcher implementation, add this method to your class.
#### `ResponseFactory` Contract: `eventStream`
**Likelihood Of Impact: Very Low**
The `Illuminate\Contracts\Routing\ResponseFactory` contract now includes an `eventStream` signature.
If you maintain a custom implementation of this contract, you should add this method.
#### `MustVerifyEmail` Contract: `markEmailAsUnverified`
**Likelihood Of Impact: Very Low**
The `Illuminate\Contracts\Auth\MustVerifyEmail` contract now includes `markEmailAsUnverified()`.
If you provide a custom implementation of this contract, add this method to remain compatible.
### Database
#### Database `upsert` With MySQL or MariaDB
**Likelihood Of Impact: Medium**
Laravel now validates that the caller provides a non-empty value for `uniqueBy`, and will throw an `InvalidArgumentException` instead of generating invalid SQL.
Although the MariaDB and MySQL database drivers ignore the `uniqueBy` value and always use the table's primary and unique indexes to detect existing records, the validation still applies. An `InvalidArgumentException` will be thrown if `uniqueBy` is empty.
#### MySQL `DELETE` Queries With `JOIN`, `ORDER BY`, and `LIMIT`
**Likelihood Of Impact: Low**
Laravel now compiles full `DELETE ... JOIN` queries including `ORDER BY` and `LIMIT` for MySQL grammar.
In previous versions, `ORDER BY` / `LIMIT` clauses could be silently ignored on joined deletes. In Laravel 13, these clauses are included in the generated SQL. As a result, database engines that do not support this syntax (such as standard MySQL / MariaDB variants) may now throw a `QueryException` instead of executing an unbounded delete.
### Eloquent
#### Model Booting and Nested Instantiation
**Likelihood Of Impact: Very Low**
Creating a new model instance while that model is still booting is now disallowed and throws a `LogicException`.
This affects code that instantiates models from inside model `boot` methods or trait `boot*` methods:
```php
protected static function boot()
{
parent::boot();
// No longer allowed during booting...
(new static())->getTable();
}
```
Move this logic outside the boot cycle to avoid nested booting.
#### Polymorphic Pivot Table Name Generation
**Likelihood Of Impact: Low**
When table names are inferred for polymorphic pivot models using custom pivot model classes, Laravel now generates pluralized names.
If your application depended on the previous singular inferred names for morph pivot tables and used custom pivot classes, you should explicitly define the table name on your pivot model.
#### Collection Model Serialization Restores Eager-Loaded Relations
**Likelihood Of Impact: Low**
When Eloquent model collections are serialized and restored (such as in queued jobs), eager-loaded relations are now restored for the collection's models.
If your code depended on relations not being present after deserialization, you may need to adjust that logic.
### HTTP Client
#### HTTP Client `Response::throw` and `throwIf` Signatures
**Likelihood Of Impact: Very Low**
The HTTP client response methods now declare their callback parameters in the method signatures:
```php
public function throw($callback = null);
public function throwIf($condition, $callback = null);
```
If you override these methods in custom response classes, ensure your method signatures are compatible.
### Notifications
#### Default Password Reset Subject
**Likelihood Of Impact: Very Low**
Laravel's default password reset mail subject has changed:
```text
// Laravel <= 12.x
Reset Password Notification
// Laravel >= 13.x
Reset your password
```
If your tests, assertions, or translation overrides depend on the previous default string, update them accordingly.
#### Queued Notifications and Missing Models
**Likelihood Of Impact: Very Low**
Queued notifications now respect the `#[DeleteWhenMissingModels]` attribute and `$deleteWhenMissingModels` property defined on the notification class.
In previous versions, missing models could still cause queued notification jobs to fail in cases where you expected them to be deleted.
### Queue
#### `JobAttempted` Event Exception Payload
**Likelihood Of Impact: Low**
The `Illuminate\Queue\Events\JobAttempted` event now exposes the exception object (or `null`) via `$exception`, replacing the previous boolean `$exceptionOccurred` property:
```php
// Laravel <= 12.x
$event->exceptionOccurred;
// Laravel >= 13.x
$event->exception;
```
If you listen for this event, update your listener code accordingly.
#### `QueueBusy` Event Property Rename
**Likelihood Of Impact: Low**
The `Illuminate\Queue\Events\QueueBusy` event property `$connection` has been renamed to `$connectionName` for consistency with other queue events.
If your listeners reference `$connection`, update them to `$connectionName`.
#### `Queue` Contract Method Additions
**Likelihood Of Impact: Very Low**
The `Illuminate\Contracts\Queue\Queue` contract now includes queue size inspection methods that were previously only declared in docblocks.
If you maintain custom queue driver implementations of this contract, add implementations for:
- `pendingSize`
- `delayedSize`
- `reservedSize`
- `creationTimeOfOldestPendingJob`
### Routing
#### Domain Route Registration Precedence
**Likelihood Of Impact: Low**
Routes with an explicit domain are now prioritized before non-domain routes in route matching.
This allows catch-all subdomain routes to behave consistently even when non-domain routes are registered earlier. If your application relied on previous registration precedence between domain and non-domain routes, review route matching behavior.
### Session
#### Session `serialization` Configuration
**Likelihood Of Impact: Low**
To help prevent PHP deserialization gadget chain attacks, the default application skeleton now sets the session `serialization` option to `json` in the `config/session.php` file.
If you are upgrading an existing application and syncing your configuration files with the Laravel 13 skeleton, updating this value from `php` to `json` will invalidate all active user sessions.
If you wish to seamlessly maintain active sessions during your upgrade, you should ensure this value remains set to `php`. However, if your application does not store PHP objects in the session and you are comfortable requiring your users to re-authenticate, we recommend updating this value to `json` for improved security.
### Scheduling
#### `withScheduling` Registration Timing
**Likelihood Of Impact: Very Low**
Schedules registered via `ApplicationBuilder::withScheduling()` are now deferred until `Schedule` is resolved.
If your application relied on immediate schedule registration timing during bootstrap, you may need to adjust that logic.
### Security
#### Request Forgery Protection
**Likelihood Of Impact: High**
Laravel's CSRF middleware has been renamed from `VerifyCsrfToken` to `PreventRequestForgery`, and now includes request-origin verification using the `Sec-Fetch-Site` header.
`VerifyCsrfToken` and `ValidateCsrfToken` remain as deprecated aliases, but direct references should be updated to `PreventRequestForgery`, especially when excluding middleware in tests or route definitions:
```php
use Illuminate\Foundation\Http\Middleware\PreventRequestForgery;
use Illuminate\Foundation\Http\Middleware\VerifyCsrfToken;
// Laravel <= 12.x
->withoutMiddleware([VerifyCsrfToken::class]);
// Laravel >= 13.x
->withoutMiddleware([PreventRequestForgery::class]);
```
The middleware configuration API now also provides `preventRequestForgery(...)`.
### Support
#### Manager `extend` Callback Binding
**Likelihood Of Impact: Low**
Custom driver closures registered via manager `extend` methods are now bound to the manager instance.
If you previously relied on another bound object (such as a service provider instance) as `$this` inside these callbacks, you should move those values into closure captures using `use (...)`.
#### `Str` Factories Reset Between Tests
**Likelihood Of Impact: Low**
Laravel now resets custom `Str` factories during test teardown.
If your tests depended on custom UUID / ULID / random string factories persisting between test methods, you should set them in each relevant test or setup hook.
#### `Js::from` Uses Unescaped Unicode By Default
**Likelihood Of Impact: Very Low**
`Illuminate\Support\Js::from` now uses `JSON_UNESCAPED_UNICODE` by default.
If your tests or frontend output comparisons depended on escaped Unicode sequences (for example `\u00e8`), update your expectations.
### Utilities
#### Symfony PHP 8.5 Polyfill and Global Function Conflicts
**Likelihood Of Impact: Low**
Laravel 13 introduces a dependency on `symfony/polyfill-php85`. On PHP versions below 8.5, this polyfill defines global functions such as `array_first()` and `array_last()` unless they have already been defined earlier during bootstrap.
These functions may conflict with legacy helper packages like `laravel/helpers` or custom global helpers using the same names. For example, the historical `array_first()` helper accepted a callback to return the first matching element, while the polyfilled version only returns the first element of the array.
To avoid conflicts and ensure consistent behavior across PHP versions, you should prefer the `Illuminate\Support\Arr` methods:
```php
use Illuminate\Support\Arr;
Arr::first($array, function ($value) {
return /* condition */;
});
```
### Views
#### Pagination Bootstrap View Names
**Likelihood Of Impact: Low**
The internal pagination view names for Bootstrap 3 defaults are now explicit:
```nothing
// Laravel <= 12.x
pagination::default
pagination::simple-default
// Laravel >= 13.x
pagination::bootstrap-3
pagination::simple-bootstrap-3
```
If your application references the old pagination view names directly, update those references.
### Miscellaneous
We also encourage you to view the changes in the `laravel/laravel` [GitHub repository](https://github.com/laravel/laravel). 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](https://github.com/laravel/laravel/compare/12.x...13.x) and choose which updates are important to you.