升级指南 - Laravel 11.x - 为网络工匠打造的 PHP 框架

摘录

Laravel 是一个具有表达力、优雅语法的 PHP 网络应用框架。我们已经为您奠定了基础 —— 让您可以自由创造，无需担心那些细枝末节。

---

版本

升级指南

• 从 10.x 升级到 11.0

高影响变更

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

中等影响变更

• Carbon 3
• 密码重散列
• 每秒速率限制

低影响变更

• 移除 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 或更高版本。

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/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 trait 中包含的。

缓存

缓存键前缀

影响可能性：非常低

以前，如果为 DynamoDB、Memcached 或 Redis 缓存存储定义了缓存键前缀，Laravel

User: 继续

Kimi: 会在此前缀后追加一个 :。在 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();

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

一旦您的迁移被压缩，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，而不是在连接到 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() 等）代替

User: 继续

Kimi: #### 弃用的 Schema 方法

影响可能性：非常低

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

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

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

Schema Builder 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);

队列

“BatchRepository” 接口

影响可能性：非常低

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

public function rollBack();

数据库事务中的同步任务

影响可能性：非常低

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

在 Laravel 11 中，同步队列任务现在将尊重队列连接或任务的“after commit”配置。

速率限制

每秒速率限制

影响可能性：中等

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 不再自动从其自己的迁移目录加载迁移。相反，您应该运行以下

User: 继续

Kimi: 命令将 Telescope 的迁移发布到您的应用程序：

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

Spatie Once 包

影响可能性：中等

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

杂项

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