升級指南

• Upgrading To 11.0 From 10.x

高度影響的更改

中度影響的更改

低影響的更改

Upgrading To 11.0 From 10.x

預計升級所需時間：15 分鐘

相依性套件更新

受影響的可能：高

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 相依性套件

請在專案的 composer.json 檔案中更新下列相依性套件：

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:

1php artisan vendor:publish --tag=cashier-migrations
2php artisan vendor:publish --tag=passport-migrations
3php artisan vendor:publish --tag=sanctum-migrations
4php artisan vendor:publish --tag=spark-migrations
5php artisan vendor:publish --tag=telescope-migrations
1php artisan vendor:publish --tag=cashier-migrations
2php artisan vendor:publish --tag=passport-migrations
3php artisan vendor:publish --tag=sanctum-migrations
4php artisan vendor:publish --tag=spark-migrations
5php 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
• Laravel Passport
• Laravel Sanctum
• Laravel Spark Stripe
• Laravel Telescope

If you have manually installed the Laravel installer, you should update the installer via Composer:

1composer global require laravel/installer:^5.6
1composer 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

受影響的可能：低

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:

1protected $authPasswordName = 'custom_password_field';
1protected $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:

1'rehash_on_login' => false,
1'rehash_on_login' => false,

The UserProvider Contract

受影響的可能：低

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:

1public function rehashPasswordIfRequired(Authenticatable $user, array $credentials, bool $force = false);
1public function rehashPasswordIfRequired(Authenticatable $user, array $credentials, bool $force = false);

The Authenticatable Contract

受影響的可能：低

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:

1public function getAuthPasswordName()
2{
3    return 'password';
4}
1public function getAuthPasswordName()
2{
3    return 'password';
4}

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

受影響的可能：非常低

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:

1if ($e instanceof AuthenticationException) {
2    $path = $e->redirectTo($request);
3}
1if ($e instanceof AuthenticationException) {
2    $path = $e->redirectTo($request);
3}

Email Verification Notification on Registration

受影響的可能：非常低

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:

1protected function configureEmailVerification()
2{
3    // ...
4}
1protected function configureEmailVerification()
2{
3    // ...
4}

快取

Cache Key Prefixes

受影響的可能：非常低

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

Enumerable Contract

受影響的可能：低

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:

1public function dump(...$args);
1public function dump(...$args);

資料庫

SQLite 3.26.0+

受影響的可能：高

If your application is utilizing an SQLite database, SQLite 3.26.0 or greater is required.

Eloquent Model casts Method

受影響的可能：低

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

受影響的可能：高

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:

1Schema::create('users', function (Blueprint $table) {
2    $table->integer('votes')->unsigned()->default(1)->comment('The vote count');
3});
1Schema::create('users', function (Blueprint $table) {
2    $table->integer('votes')->unsigned()->default(1)->comment('The vote count');
3});

Later, you write a migration that changes the column to be nullable as well:

1Schema::table('users', function (Blueprint $table) {
2    $table->integer('votes')->nullable()->change();
3});
1Schema::table('users', function (Blueprint $table) {
2    $table->integer('votes')->nullable()->change();
3});

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:

1Schema::table('users', function (Blueprint $table) {
2    $table->integer('votes')
3        ->unsigned()
4        ->default(1)
5        ->comment('The vote count')
6        ->nullable()
7        ->change();
8});
1Schema::table('users', function (Blueprint $table) {
2    $table->integer('votes')
3        ->unsigned()
4        ->default(1)
5        ->comment('The vote count')
6        ->nullable()
7        ->change();
8});

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:

1// Add an index...
2$table->bigIncrements('id')->primary()->change();
3 
4// Drop an index...
5$table->char('postal_code', 10)->unique(false)->change();
1// Add an index...
2$table->bigIncrements('id')->primary()->change();
3 
4// Drop an index...
5$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:

1php artisan schema:dump
1php 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

受影響的可能：高

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:

1$table->double('amount');
1$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:

1$table->float('amount', precision: 53);
1$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:

1$table->decimal('amount', total: 8, places: 2)->unsigned();
2$table->double('amount')->unsigned();
3$table->float('amount', precision: 53)->unsigned();
1$table->decimal('amount', total: 8, places: 2)->unsigned();
2$table->double('amount')->unsigned();
3$table->float('amount', precision: 53)->unsigned();

Dedicated MariaDB Driver

受影響的可能：非常低

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:

1'driver' => 'mariadb',
2'url' => env('DB_URL'),
3'host' => env('DB_HOST', '127.0.0.1'),
4'port' => env('DB_PORT', '3306'),
5// ...
1'driver' => 'mariadb',
2'url' => env('DB_URL'),
3'host' => env('DB_HOST', '127.0.0.1'),
4'port' => env('DB_PORT', '3306'),
5// ...

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:

1Schema::table('users', function (Blueprint $table) {
2    $table->char('uuid', 36);
3 
4    // ...
5});
1Schema::table('users', function (Blueprint $table) {
2    $table->char('uuid', 36);
3 
4    // ...
5});

Spatial Types

受影響的可能：低

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:

1$table->geometry('shapes');
2$table->geography('coordinates');
1$table->geometry('shapes');
2$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:

1$table->geometry('dimension', subtype: 'polygon', srid: 0);
2$table->geography('latitude', subtype: 'point', srid: 4326);
1$table->geometry('dimension', subtype: 'polygon', srid: 0);
2$table->geography('latitude', subtype: 'point', srid: 4326);

The isGeometry and projection column modifiers of the PostgreSQL grammar have been removed accordingly.

Doctrine DBAL Removal

受影響的可能：低

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:

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

受影響的可能：非常低

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:

1Schema::connection('database')->hasTable('schema.table');
1Schema::connection('database')->hasTable('schema.table');

Schema Builder getColumnType() Method

受影響的可能：非常低

The Schema::getColumnType() method now always returns actual type of the given column, not the Doctrine DBAL equivalent type.

Database Connection Interface

受影響的可能：非常低

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:

1public function scalar($query, $bindings = [], $useReadPdo = true);
1public function scalar($query, $bindings = [], $useReadPdo = true);

Dates

Carbon 3

受影響的可能性：中等

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 and documentation for detailed information on how to handle these and other changes.

郵件

The Mailer Contract

受影響的可能：非常低

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:

1public function sendNow($mailable, array $data = [], $callback = null);
1public function sendNow($mailable, array $data = [], $callback = null);

套件

Publishing Service Providers to the Application

受影響的可能：非常低

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.

1use Illuminate\Support\ServiceProvider;
2 
3ServiceProvider::addProviderToBootstrapFile(Provider::class);
1use Illuminate\Support\ServiceProvider;
2 
3ServiceProvider::addProviderToBootstrapFile(Provider::class);

佇列 - Queue

The BatchRepository Interface

受影響的可能：非常低

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:

1public function rollBack();
1public function rollBack();

Synchronous Jobs in Database Transactions

受影響的可能：非常低

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

受影響的可能性：中等

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:

1new GlobalLimit($attempts, 2 * 60);
1new 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:

1new Limit($key, $attempts, 2 * 60);
1new 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:

1new ThrottlesExceptions($attempts, 2 * 60);
2new ThrottlesExceptionsWithRedis($attempts, 2 * 60);
1new ThrottlesExceptions($attempts, 2 * 60);
2new ThrottlesExceptionsWithRedis($attempts, 2 * 60);

Cashier Stripe

Updating Cashier Stripe

受影響的可能：高

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:

1php artisan vendor:publish --tag=cashier-migrations
1php artisan vendor:publish --tag=cashier-migrations

Please review the complete Cashier Stripe upgrade guide for additional breaking changes.

Spark (Stripe)

Updating Spark Stripe

受影響的可能：高

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:

1php artisan vendor:publish --tag=spark-migrations
1php artisan vendor:publish --tag=spark-migrations

Please review the complete Spark Stripe upgrade guide for additional breaking changes.

Passport

Updating Passport

受影響的可能：高

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:

1php artisan vendor:publish --tag=passport-migrations
1php 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:

1public function boot(): void
2{
3    Passport::enablePasswordGrant();
4}
1public function boot(): void
2{
3    Passport::enablePasswordGrant();
4}

Sanctum

Updating Sanctum

受影響的可能：高

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:

1php artisan vendor:publish --tag=sanctum-migrations
1php 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:

1'middleware' => [
2    'authenticate_session' => Laravel\Sanctum\Http\Middleware\AuthenticateSession::class,
3    'encrypt_cookies' => Illuminate\Cookie\Middleware\EncryptCookies::class,
4    'validate_csrf_token' => Illuminate\Foundation\Http\Middleware\ValidateCsrfToken::class,
5],
1'middleware' => [
2    'authenticate_session' => Laravel\Sanctum\Http\Middleware\AuthenticateSession::class,
3    'encrypt_cookies' => Illuminate\Cookie\Middleware\EncryptCookies::class,
4    'validate_csrf_token' => Illuminate\Foundation\Http\Middleware\ValidateCsrfToken::class,
5],

Telescope

Updating Telescope

受影響的可能：高

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:

1php artisan vendor:publish --tag=telescope-migrations
1php artisan vendor:publish --tag=telescope-migrations

Spatie Once Package

受影響的可能性：中等

Laravel 11 now provides its own once function 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.

其他

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.