升级指南

从 10.x 升级到 11.0

低影响变更

移除 Doctrine DBAL
Eloquent 模型 casts 方法
空间类型
Spatie Once 包
Enumerable 合约
UserProvider 合约
Authenticatable 合约

从 10.x 升级到 11.0

预计升级时间：15 分钟

我们尝试记录每一个可能的重大变更。由于某些重大变更只在框架的某些不常见部分中，因此这些变更中只有一部分可能会实际影响您的应用程序。想节省时间吗？您可以使用 Laravel Shift 来帮助自动化您的应用程序升级。

更新依赖

影响可能性：高

PHP 8.2.0 要求

Laravel 现在要求 PHP 8.2.0 或更高版本。

curl 7.34.0 要求

Laravel 的 HTTP 客户端现在要求 curl 7.34.0 或更高版本。

Composer 依赖

您应该在应用程序的 composer.json 文件中更新以下依赖项：

将 laravel/framework 更新到 ^11.0
将 nunomaduro/collision 更新到 ^8.1
将 laravel/breeze 更新到 ^2.0（如果已安装）
将 laravel/cashier 更新到 ^15.0（如果已安装）
将 laravel/dusk 更新到 ^8.0（如果已安装）
将 laravel/jetstream 更新到 ^5.0（如果已安装）
将 laravel/octane 更新到 ^2.3（如果已安装）
将 laravel/passport 更新到 ^12.0（如果已安装）
将 laravel/sanctum 更新到 ^4.0（如果已安装）
将 laravel/scout 更新到 ^10.0（如果已安装）
将 laravel/spark-stripe 更新到 ^5.0（如果已安装）
将 laravel/telescope 更新到 ^5.0（如果已安装）
将 inertiajs/inertia-laravel 更新到 ^1.0（如果已安装）

如果您的应用程序使用了 Laravel Cashier Stripe、Passport、Sanctum、Spark Stripe 或 Telescope，您需要将它们的迁移发布到您的应用程序中。Cashier Stripe、Passport、Sanctum、Spark Stripe 和 Telescope 不再自动从它们自己的迁移目录加载迁移。因此，您应该运行以下命令将它们的迁移发布到您的应用程序中：

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

working 翻译于

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:

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

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, you may disable this behavior 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:

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:

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:

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

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:

public function dump(...$args);

Database

SQLite 3.35.0+

Likelihood Of Impact: High

If your application is utilizing an SQLite database, SQLite 3.35.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:

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:

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:

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:

// 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:

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:

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

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

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

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:

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

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

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:

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

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.

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:

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:

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:

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:

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:

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

Please review the complete Cashier Stripe upgrade guide 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:

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

Please review the complete Spark Stripe upgrade guide 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:

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:

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:

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

Spatie Once Package

Likelihood Of Impact: Medium

Laravel 11 现在提供了自己的 once 函数以确保给定的闭包仅执行一次。因此，如果您的应用程序依赖于spatie/once包，则应将其从应用程序的composer.json文件中删除以避免冲突。

杂项

我们还建议您查看 laravel/laravel GitHub 代码库中的变更记录。虽然其中许多更改并非必需，但您可能希望让这些文件与您的应用程序保持同步。本升级指南将涵盖其中的一些更改，但其他更改（如配置文件或注释的更改）则不包括在内。您可以使用 GitHub 比较工具轻松查看这些变更，并选择更新那些对您来说是重要的变更记录。