升级指南

• 高影响变更
• 中等影响变更
• 低影响变更
• 从 10.x 升级到 11.0
  • 更新依赖项
  • 应用结构
  • 认证
  • 缓存
  • 集合
  • 数据库
  • 日期
  • 邮件
  • 包
  • 队列
  • 速率限制
  • Cashier Stripe
  • Spark (Stripe)
  • Passport
  • Sanctum
  • Telescope
  • Spatie Once 包
  • 杂项

高影响变更

• 更新依赖项
• 应用结构
• 浮点类型
• 修改列
• SQLite 最低版本
• 更新 Sanctum

中等影响变更

• Carbon 3
• 密码重哈希
• 每秒速率限制

低影响变更

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

从 10.x 升级到 11.0

预计升级时间：15 分钟

NOTE

我们尝试记录每一个可能的破坏性变更。由于这些破坏性变更中的一些只出现在框架的不太明显的部分，因此只有部分变更可能实际影响到您的应用程序。想节省时间？您可以使用 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/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

此外，您应该查看这些包的升级指南，以确保您了解任何其他破坏性变更：

• Laravel Cashier Stripe
• Laravel Passport
• Laravel Sanctum
• Laravel Spark Stripe
• Laravel Telescope

如果您手动安装了 Laravel 安装程序，您应该通过 Composer 更新安装程序：

composer global require laravel/installer:^5.6

最后，如果您之前已将 doctrine/dbal Composer 依赖项添加到您的应用程序中，您可以将其移除，因为 Laravel 不再依赖此包。

应用结构

Laravel 11 引入了一个新的默认应用结构，包含更少的默认文件。具体来说，新的 Laravel 应用包含更少的服务提供者、中间件和配置文件。

然而，我们不推荐从 Laravel 10 升级到 Laravel 11 的应用尝试迁移它们的应用结构，因为 Laravel 11 已经仔细调整以支持 Laravel 10 的应用结构。

认证

密码重哈希

Laravel 11 将在认证期间自动重新哈希用户的密码，如果自密码上次哈希以来您的哈希算法的“工作因子”已更新。

通常，这不应该干扰您的应用程序；然而，您可以通过在应用程序的 config/hashing.php 配置文件中添加 rehash_on_login 选项来禁用此行为：

'rehash_on_login' => false,

UserProvider 合约

影响可能性：低

Illuminate\Contracts\Auth\UserProvider 合约收到了一个新的 rehashPasswordIfRequired 方法。当应用程序的哈希算法工作因子发生变化时，此方法负责重新哈希并存储用户的密码。

如果您的应用程序或包定义了实现此接口的类，您应该将新的 rehashPasswordIfRequired 方法添加到您的实现中。一个参考实现可以在 Illuminate\Auth\EloquentUserProvider 类中找到：

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

Authenticatable 合约

影响可能性：低

Illuminate\Contracts\Auth\Authenticatable 合约收到了一个新的 getAuthPasswordName 方法。此方法负责返回您的认证实体的密码列的名称。

如果您的应用程序或包定义了实现此接口的类，您应该将新的 getAuthPasswordName 方法添加到您的实现中：

public function getAuthPasswordName()
{
    return 'password';
}

Laravel 包含的默认 User 模型自动接收此方法，因为该方法包含在 Illuminate\Auth\Authenticatable 特性中。

AuthenticationException 类

影响可能性：非常低

Illuminate\Auth\AuthenticationException 类的 redirectTo 方法现在需要一个 Illuminate\Http\Request 实例作为其第一个参数。如果您手动捕获此异常并调用 redirectTo 方法，您应该相应地更新您的代码：

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

缓存

缓存键前缀

影响可能性：非常低

以前，如果为 DynamoDB、Memcached 或 Redis 缓存存储定义了缓存键前缀，Laravel 会在前缀后附加 :。在 Laravel 11 中，缓存键前缀不会接收 : 后缀。如果您想保持之前的前缀行为，您可以手动将 : 后缀添加到您的缓存键前缀。

集合

Enumerable 合约

影响可能性：低

Illuminate\Support\Enumerable 合约的 dump 方法已更新，以接受可变参数 ...$args。如果您正在实现这个接口，您应该相应地更新您的实现：

public function dump(...$args);

数据库

SQLite 3.35.0+

影响可能性：高

如果您的应用程序正在使用 SQLite 数据库，需要 SQLite 3.35.0 或更高版本。

Eloquent 模型 casts 方法

影响可能性：低

基础 Eloquent 模型类现在定义了一个 casts 方法，以支持属性转换的定义。如果您的应用程序的模型定义了一个 casts 关系，它可能与基础 Eloquent 模型类现在存在的 casts 方法冲突。

修改列

影响可能性：高

当修改列时，您现在必须在更改后显式包括您希望保留在列定义上的所有修饰符。任何缺失的属性都将被删除。例如，要保留 unsigned、default 和 comment 属性，您必须在更改列时显式调用每个修饰符，即使这些属性已经通过之前的迁移分配给列。

例如，假设您有一个迁移创建了一个带有 unsigned、default 和 comment 属性的 votes 列：

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

后来，您编写了一个将该列更改为 nullable 的迁移：

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

在 Laravel 10 中，此迁移将保留列上的 unsigned、default 和 comment 属性。然而，在 Laravel 11 中，迁移现在必须还包括之前在列上定义的所有属性。否则，它们将被删除：

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

change 方法不会更改列的索引。因此，您可以使用索引修饰符在修改列时显式添加或删除索引：

// 添加索引...
$table->bigIncrements('id')->primary()->change();

// 删除索引...
$table->char('postal_code', 10)->unique(false)->change();

如果您不希望更新应用程序中所有现有的“更改”迁移以保留列的现有属性，您可以简单地压缩您的迁移：

php artisan schema:dump

一旦您的迁移被压缩，Laravel 将使用您应用程序的架构文件“迁移”数据库，然后运行任何待处理的迁移。

浮点类型

影响可能性：高

double 和 float 迁移列类型已重写，以在所有数据库中保持一致。

double 列类型现在创建一个没有总位数和小数位（小数点后的数字）的 DOUBLE 等效列，这是标准 SQL 语法。因此，您可以移除 $total 和 $places 参数：

$table->double('amount');

float 列类型现在创建一个没有总位数和小数位（小数点后的数字）的 FLOAT 等效列，但有一个可选的 $precision 规范来确定存储大小为 4 字节单精度列或 8 字节双精度列。因此，您可以移除 $total 和 $places 参数，并根据您的数据库文档指定可选的 $precision 到您希望的值：

$table->float('amount', precision: 53);

已移除 unsignedDecimal、unsignedDouble 和 unsignedFloat 方法，因为这些列类型的无符号修饰符已被 MySQL 弃用，并且从未在其他数据库系统上标准化。然而，如果您希望继续使用这些列类型的已弃用无符号属性，您可以将 unsigned 方法链接到列的定义：

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

专用 MariaDB 驱动

影响可能性：非常低

Laravel 11 添加了一个专用的数据库驱动来连接 MariaDB 数据库，而不是始终使用 MySQL 驱动。

如果您的应用程序连接到 MariaDB 数据库，您可以将连接配置更新为新的 mariadb 驱动，以便在将来从 MariaDB 特定的功能中受益：

'driver' => 'mariadb',
'url' => env('DB_URL'),
'host' => env('DB_HOST', '127.0.0.1'),
'port' => env('DB_PORT', '3306'),
// ...

目前，新的 MariaDB 驱动的行为类似于当前的 MySQL 驱动，但有一个例外：uuid 架构构建器方法创建原生 UUID 列而不是 char(36) 列。

如果您的现有迁移使用了 uuid 架构构建器方法，并且您选择使用新的 mariadb 数据库驱动，您应该将您的迁移中的 uuid 方法调用更新为 char，以避免破坏性变更或意外行为：

Schema::table('users', function (Blueprint $table) {
    $table->char('uuid', 36);

    // ...
});

空间类型

影响可能性：低

数据库迁移的空间列类型已重写，以在所有数据库中保持一致。因此，您可以从您的迁移中移除 point、lineString、polygon、geometryCollection、multiPoint、multiLineString、multiPolygon 和 multiPolygonZ 方法，改用 geometry 或 geography 方法：

$table->geometry('shapes');
$table->geography('coordinates');

要在 MySQL、MariaDB 和 PostgreSQL 上显式限制存储在列中的值的类型或空间参考系统标识符，您可以将 subtype 和 srid 传递给方法：

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

相应地，PostgreSQL 语法的 isGeometry 和 projection 列修饰符已被移除。

移除 Doctrine DBAL

影响可能性：低

以下列表中的 Doctrine DBAL 相关类和方法已被移除。Laravel 不再依赖此包，并且不再需要注册自定义 Doctrine 类型来正确创建和修改之前需要自定义类型的各种列类型：

• Illuminate\Database\Schema\Builder::$alwaysUsesNativeSchemaOperationsIfPossible 类属性
• Illuminate\Database\Schema\Builder::useNativeSchemaOperationsIfPossible() 方法
• Illuminate\Database\Connection::usingNativeSchemaOperations() 方法
• Illuminate\Database\Connection::isDoctrineAvailable() 方法
• Illuminate\Database\Connection::getDoctrineConnection() 方法
• Illuminate\Database\Connection::getDoctrineSchemaManager() 方法
• Illuminate\Database\Connection::getDoctrineColumn() 方法
• Illuminate\Database\Connection::registerDoctrineType() 方法
• Illuminate\Database\DatabaseManager::registerDoctrineType() 方法
• Illuminate\Database\PDO 目录
• Illuminate\Database\DBAL\TimestampType 类
• Illuminate\Database\Schema\Grammars\ChangeColumn 类
• Illuminate\Database\Schema\Grammars\RenameColumn 类
• Illuminate\Database\Schema\Grammars\Grammar::getDoctrineTableDiff() 方法

此外，不再需要通过您应用程序的 database 配置文件中的 dbal.types 注册自定义 Doctrine 类型。

如果您之前使用 Doctrine DBAL 来检视您的数据库及其相关表，您可以改用 Laravel 的新原生架构方法（Schema::getTables()、Schema::getColumns()、Schema::getIndexes()、Schema::getForeignKeys() 等）。

已弃用的架构方法

影响可能性：非常低

已弃用、基于 Doctrine 的 Schema::getAllTables()、Schema::getAllViews() 和 Schema::getAllTypes() 方法已被新的 Laravel 原生 Schema::getTables()、Schema::getViews() 和 Schema::getTypes() 方法取代。

当使用 PostgreSQL 和 SQL Server 时，新的架构方法不会接受三部分引用（例如 database.schema.table）。因此，您应该使用 connection() 来声明数据库：

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

架构构建器 getColumnType() 方法

影响可能性：非常低

Schema::getColumnType() 方法现在总是返回给定列的实际类型，而不是 Doctrine DBAL 等效类型。

数据库连接接口

影响可能性：非常低

Illuminate\Database\ConnectionInterface 接口收到了一个新的 scalar 方法。如果您正在定义自己的此接口的实现，您应该将 scalar 方法添加到您的实现中：

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

日期

Carbon 3

影响可能性：中等

Laravel 11 支持 Carbon 2 和 Carbon 3。Carbon 是一个广泛被 Laravel 和整个生态系统的包使用的日期操作库。如果您安装了 Carbon 3，您应该查看 Carbon 的变更日志。

邮件

Mailer 合约

影响可能性：非常低

Illuminate\Contracts\Mail\Mailer 合约收到了一个新的 sendNow 方法。如果您的应用程序或包手动实现了这个合约，您应该将新的 sendNow 方法添加到您的实现中：

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

包

将服务提供者发布到应用程序

影响可能性：非常低

如果您编写了一个 Laravel 包，该包手动将服务提供者发布到应用程序的 app/Providers 目录，并手动修改应用程序的 config/app.php 配置文件来注册服务提供者，您应该更新您的包以使用新的 ServiceProvider::addProviderToBootstrapFile 方法。

addProviderToBootstrapFile 方法将自动将您已发布的服务提供者添加到应用程序的 bootstrap/providers.php 文件中，因为新的 Laravel 11 应用程序中的 config/app.php 配置文件中不存在 providers 数组。

use Illuminate\Support\ServiceProvider;

ServiceProvider::addProviderToBootstrapFile(Provider::class);

队列

BatchRepository 接口

影响可能性：非常低

Illuminate\Bus\BatchRepository 接口收到了一个新的 rollBack 方法。如果您在自己的包或应用程序中实现了这个接口，您应该将这个方法添加到您的实现中：

public function rollBack();

数据库事务中的同步作业

影响可能性：非常低

以前，同步作业（使用 sync 队列驱动的作业）会立即执行，不管队列连接的 after_commit 配置选项是否设置为 true 或作业上是否调用了 afterCommit 方法。

在 Laravel 11 中，同步队列作业现在将尊重队列连接或作业的“提交后”配置。

速率限制

每秒速率限制

影响可能性：中等

Laravel 11 支持每秒速率限制，而不仅限于每分钟的粒度。您应该注意与此变更相关的各种潜在破坏性变更。

GlobalLimit 类构造函数现在接受秒而不是分钟。这个类没有文档记录，通常不会被您的应用程序使用：

new GlobalLimit($attempts, 2 * 60);

Limit 类构造函数现在接受秒而不是分钟。这个类的所有文档用法都限于静态构造函数，如 Limit::perMinute 和 Limit::perSecond。然而，如果您手动实例化这个类，您应该更新您的应用程序以向类的构造函数提供秒：

new Limit($key, $attempts, 2 * 60);

Limit 类的 decayMinutes 属性已重命名为 decaySeconds，现在包含秒而不是分钟。

Illuminate\Queue\Middleware\ThrottlesExceptions 和 Illuminate\Queue\Middleware\ThrottlesExceptionsWithRedis 类构造函数现在接受秒而不是分钟：

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

Cashier Stripe

更新 Cashier Stripe

影响可能性：高

Laravel 11 不再支持 Cashier Stripe 14.x。因此，您应该在您的 composer.json 文件中将您的 Laravel Cashier Stripe 依赖项更新为 ^15.0。

Cashier Stripe 15.0 不再自动从其自己的迁移目录加载迁移。相反，您应该运行以下命令将 Cashier Stripe 的迁移发布到您的应用程序：

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

请查看完整的 Cashier Stripe 升级指南 以了解其他破坏性变更。

Spark (Stripe)

更新 Spark Stripe

影响可能性：高

Laravel 11 不再支持 Laravel Spark Stripe 4.x。因此，您应该在您的 composer.json 文件中将您的 Laravel Spark Stripe 依赖项更新为 ^5.0。

Spark Stripe 5.0 不再自动从其自己的迁移目录加载迁移。相反，您应该运行以下命令将 Spark Stripe 的迁移发布到您的应用程序：

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

请查看完整的 Spark Stripe 升级指南 以了解其他破坏性变更。

Passport

更新 Passport

影响可能性：高

Laravel 11 不再支持 Laravel Passport 11.x。因此，您应该在您的 composer.json 文件中将您的 Laravel Passport 依赖项更新为 ^12.0。

Passport 12.0 不再自动从其自己的迁移目录加载迁移。相反，您应该运行以下命令将 Passport 的迁移发布到您的应用程序：

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

此外，默认情况下禁用密码授权类型。您可以通过在应用程序的 AppServiceProvider 的 boot 方法中调用 enablePasswordGrant 方法来启用它：

public function boot(): void
{
    Passport::enablePasswordGrant();
}

Sanctum

更新 Sanctum

影响可能性：高

Laravel 11 不再支持 Laravel Sanctum 3.x。因此，您应该在您的 composer.json 文件中将您的 Laravel Sanctum 依赖项更新为 ^4.0。

Sanctum 4.0 不再自动从其自己的迁移目录加载迁移。相反，您应该运行以下命令将 Sanctum 的迁移发布到您的应用程序：

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

然后，在您的应用程序的 config/sanctum.php 配置文件中，您应该将 authenticate_session、encrypt_cookies 和 validate_csrf_token 中间件的引用更新为以下内容：

'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

更新 Telescope

影响可能性：高

Laravel 11 不再支持 Laravel Telescope 4.x。因此，您应该在您的 composer.json 文件中将您的 Laravel Telescope 依赖项更新为 ^5.0。

Telescope 5.0 不再自动从其自己的迁移目录加载迁移。相反，您应该运行以下命令将 Telescope 的迁移发布到您的应用程序：

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

Spatie Once 包

影响可能性：中等

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

杂项

我们还鼓励您查看 laravel/laravel GitHub 仓库 中的变更。虽然这些变更中的许多不是必需的，但您可能希望将这些文件与您的应用程序同步。这些变更中的一些将在本升级指南中涵盖，但其他一些，如配置文件或注释的变更，将不会。您可以使用 GitHub 比较工具 轻松查看这些变更，并选择哪些更新对您来说很重要。