升级指南

• 从 10.x 升级到 11.0

高影响变化

中等影响变化

较小影响变化

从 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 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('投票数');
});

后来，你编写了一个迁移，将该列更改为同时可为空：

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('投票数')
        ->nullable()
        ->change();
});

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

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

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

如果你不想更新应用程序中所有现有的“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 驱动，以便在将来从 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 类型对于正确创建和修改之前需要自定义类型的各种列类型不再必要：

此外，通过应用程序的 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，请注意 diffIn* 方法现在返回浮点数，并且可能返回负值以指示时间方向，这与 Carbon 2 的行为有显著不同。查看 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_csfr_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 比较工具 轻松查看变更，并选择对你而言重要的更新。

---

原文地址：cndocs/11.x/up...

译文地址：cndocs/11.x/up...