升级指南

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

高影响更改

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

中等影响变化

• Carbon 3
• 密码重新哈希
• 每秒速率限制
• Spatie Once 套餐

低影响变化

• Doctrine DBAL 删除
• Eloquent Model Casts 方法
• Spatial 类型
• 可枚举 Contract
• UserProvider Contract
• Authenticatable Contract

从 10.x 升级到 11.0

预计升级时间:15 分钟

NOTE

我们尝试记录所有可能的中断性变更。由于其中一些重大更改位于框架的模糊部分，因此只有一部分这些更改可能会实际影响您的应用程序。想要节省时间？您可以使用 Laravel Shift 来帮助自动化应用程序升级。

更新依赖项

**影响性:高 **

PHP 8.2.0 Required

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

curl 7.34.0 Required

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

Composer Dependencies

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

• laravel/framework to ^11.0
• nunomaduro/collision to ^8.1
• laravel/breeze to ^2.0 (如果已安装)
• laravel/cashier to ^15.0 (如果已安装)
• laravel/dusk to ^8.0 (如果已安装)
• laravel/jetstream to ^5.0 (如果已安装)
• laravel/octane to ^2.3 (如果已安装)
• laravel/passport to ^12.0 (如果已安装)
• laravel/sanctum to ^4.0 (如果已安装)
• laravel/scout to ^10.0 (如果已安装)
• laravel/spark-stripe to ^5.0 (如果已安装)
• laravel/telescope to ^5.0 (如果已安装)
• livewire/livewire to ^3.4 (如果已安装)
• inertiajs/inertia-laravel to ^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 11 的 Laravel 10 应用程序尝试迁移其应用程序结构，因为 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);

可验证的 Contract

影响性:低

Illuminate\Contracts\Auth\Authenticatable 合约收到了新的 getAuthPasswordName 方法。此方法负责返回可验证实体的 password 列的名称。

如果您的应用程序或软件包定义了实现此接口的类，则应将新的 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);
}

Cache 缓存

缓存键前缀

影响性:非常低

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

Collections

可枚举 Contract

影响性:低

Illuminate\Support\Enumerable 合约的 dump 方法已更新为接受可变参数 ...$args 参数。如果要实现此接口，则应相应地更新实现:

public function dump(...$args);

数据库

SQLite 3.26.0+

影响性:高

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

Eloquent Model casts 方法

影响性:低

Eloquent 基础模型类现在定义了一个 casts 方法，以支持属性 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');
});

稍后，您编写了一个迁移，将列也更改为可为 null:

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” 迁移以保留列的现有属性，则只需压缩迁移即可:

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方法已被删除，因为这些列类型的unsigned修饰符已被 MySQL 弃用，并且从未在其他数据库系统上标准化。但是，如果您希望继续为这些列类型使用已弃用的 unsigned 属性，则可以将 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 不再依赖于此包，并且不再需要注册自定义 Doctrines 类型来正确创建和更改以前需要自定义类型的各种列类型:

• 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() 方法

此外，不再需要通过应用程序数据库配置文件中的 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 接口收到了一个新的标量方法。如果要定义此接口的 implementation ，则应将 scalar 方法添加到你的 implementation:

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

日期

Carbon 3

影响性:中等

Laravel 11 支持 Carbon 2 和 Carbon 3。Carbon 是一个日期操作库，被 Laravel 和整个生态系统中的包广泛使用。如果您升级到 Carbon 3，请注意 diffIn* 方法现在返回浮点数，并且可能返回负值来指示时间方向，这与 Carbon 2 相比是一个重大变化。查看 Carbon 的更改日志，了解有关如何处理这些更改和其他更改的详细信息。

Mail 邮件

Mailer Contract

影响性:非常低

Illuminate\Contracts\Mail\Mailer 合同收到了一个新的 sendNow 方法。如果您的应用程序或包正在手动实现此协定，则应将新的 sendNow 方法添加到您的实现中:

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

Packages 包

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

影响性:非常低

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

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

use Illuminate\Support\ServiceProvider;

ServiceProvider::addProviderToBootstrapFile(Provider::class);

Queues 队列

BatchRepository 接口

影响性:非常低

Illuminate\Bus\BatchRepository 接口已收到新的 rollBack 方法。如果要在自己的包或应用程序中实现此接口，则应将此方法添加到实现中:

public function rollBack();

数据库事务中的同步作业

影响性:非常低

以前，同步作业（使用同步队列驱动程序的作业）将立即执行，无论队列连接的 after_commit 配置选项是设置为 true，还是在作业上调用了 afterCommit 方法。

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

速率限制

每秒速率限制

影响性:中等

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

GlobalLimit 类构造函数现在接受秒而不是分钟。此类未记录在案，通常不会由应用程序使用:

new GlobalLimit($attempts, 2 * 60);

Limit 类构造函数现在接受秒而不是分钟。此类的所有记录用法仅限于静态构造函数，例如 Limit::p erMinute 和 Limit::p erSecond。但是，如果要手动实例化此类，则应更新应用程序以向类的构造函数提供秒数:

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)

Updating Spark Stripe

Likelihood Of Impact: High

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

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

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

Updating Telescope

影响性:高

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

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

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

Spatie Once 套餐

影响性:高

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

杂项

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