Appearance
升级指南
高影响更改
中等影响变化
低影响变化
从 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 不再自动从自己的迁移目录加载迁移。因此,您应该运行以下命令将其迁移发布到您的应用程序:
bash
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 安装程序,则应通过 Composer 更新安装程序:
bash
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
中找到参考实现:
php
public function rehashPasswordIfRequired(Authenticatable $user, array $credentials, bool $force = false);
可验证的 Contract
影响性:低
Illuminate\Contracts\Auth\Authenticatable
合约收到了新的 getAuthPasswordName
方法。此方法负责返回可验证实体的 password 列的名称。
如果您的应用程序或软件包定义了实现此接口的类,则应将新的 getAuthPasswordName
方法添加到您的实现中:
php
public function getAuthPasswordName()
{
return 'password';
}
Laravel 附带的默认 User
模型会自动接收此方法,因为该方法包含在 Illuminate\Auth\Authenticatable
特征中。
AuthenticationException 类
影响性:非常低
该 Illuminate\Auth\AuthenticationException
类的 redirectTo
方法现在需要一个 Illuminate\Http\Request
实例作为其第一个参数。如果要手动捕获此异常并调用 redirectTo
方法,则应相应地更新代码:
php
if ($e instanceof AuthenticationException) {
$path = $e->redirectTo($request);
}
Cache 缓存
缓存键前缀
影响性:非常低
以前,如果为 DynamoDB、Memcached 或 Redis 缓存存储定义了缓存键前缀,Laravel 会在前缀后附加一个 :
。在 Laravel 11 中,缓存键前缀不接收 :
后缀。如果您想保持以前的前缀行为,可以手动将 :
后缀添加到缓存键前缀中。
Collections
可枚举 Contract
影响性:低
Illuminate\Support\Enumerable
合约的 dump
方法已更新为接受可变参数 ...$args
参数。如果要实现此接口,则应相应地更新实现:
php
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
列:
php
Schema::create('users', function (Blueprint $table) {
$table->integer('votes')->unsigned()->default(1)->comment('The vote count');
});
稍后,您编写了一个迁移,将列也更改为可为 null
:
php
Schema::table('users', function (Blueprint $table) {
$table->integer('votes')->nullable()->change();
});
在 Laravel 10 中,此迁移将保留列的 unsigned
、default
和 comment
属性。但是,在 Laravel 11 中,迁移现在还必须包括之前在列上定义的所有属性。否则,它们将被丢弃:
php
Schema::table('users', function (Blueprint $table) {
$table->integer('votes')
->unsigned()
->default(1)
->comment('The vote count')
->nullable()
->change();
});
change
方法不会更改列的索引。因此,在修改列时,您可以使用索引修饰符显式添加或删除索引:
php
// 添加索引...
$table->bigIncrements('id')->primary()->change();
// 删除索引...
$table->char('postal_code', 10)->unique(false)->change();
如果您不想更新应用程序中的所有现有 “change” 迁移以保留列的现有属性,则只需压缩迁移即可:
bash
php artisan schema:dump
迁移被压缩后,Laravel 将在运行任何待处理的迁移之前使用应用程序的架构文件“迁移”数据库。
浮点类型
影响性:高
double
和 float
迁移列类型已重写,以便在所有数据库中保持一致。
double
列类型现在创建一个 DOUBLE
等效列,没有总位数和位数(小数点后的数字),这是标准 SQL 语法。因此,您可以删除 $total
和 $places
的参数:
php
$table->double('amount');
float
列类型现在创建一个 FLOAT
等效列,没有总位数和位数(小数点后的数字),但具有可选的 $precision
规范,用于将存储大小确定为 4 字节单精度列或 8 字节双精度列。因此,您可以删除 $total
和 $places
的参数,并根据数据库的文档将可选$precision
指定为所需的值:
php
$table->float('amount', precision: 53);
unsignedDecimal
、unsignedDouble
和unsignedFloat
方法已被删除,因为这些列类型的unsigned修饰符已被 MySQL 弃用,并且从未在其他数据库系统上标准化。但是,如果您希望继续为这些列类型使用已弃用的 unsigned 属性,则可以将 unsigned
方法链接到列的定义上:
php
$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
以避免中断性变更或意外行为:
php
Schema::table('users', function (Blueprint $table) {
$table->char('uuid', 36);
// ...
});
空间类型
影响性:低
数据库迁移的空间列类型已重写,以便在所有数据库中保持一致。因此,您可以从迁移中删除 point
、lineString
、polygon
、geometryCollection
、multiPoint
、multiLineString
、multiPolygon
和 multiPolygonZ
方法,并改用 geometry
或 geography
方法:
php
$table->geometry('shapes');
$table->geography('coordinates');
要显式限制 MySQL、MariaDB 和 PostgreSQL 上列中存储的值的类型或空间参考系统标识符,您可以将 subtype
和 srid
传递给该方法:
php
$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()
来声明数据库:
php
Schema::connection('database')->hasTable('schema.table');
架构构建器 getColumnType() 方法
影响性:非常低
Schema::getColumnType()
方法现在始终返回给定列的实际类型,而不是 Doctrine DBAL 等效类型。
数据库连接接口
影响性:非常低
Illuminate\Database\ConnectionInterface
接口收到了一个新的标量
方法。如果要定义此接口的 implementation ,则应将 scalar
方法添加到你的 implementation:
php
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
方法添加到您的实现中:
php
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
配置文件中不存在。
php
use Illuminate\Support\ServiceProvider;
ServiceProvider::addProviderToBootstrapFile(Provider::class);
Queues 队列
BatchRepository 接口
影响性:非常低
Illuminate\Bus\BatchRepository
接口已收到新的 rollBack
方法。如果要在自己的包或应用程序中实现此接口,则应将此方法添加到实现中:
php
public function rollBack();
数据库事务中的同步作业
影响性:非常低
以前,同步作业(使用同步
队列驱动程序的作业)将立即执行,无论队列连接的 after_commit
配置选项是设置为 true
,还是在作业上调用了 afterCommit
方法。
在 Laravel 11 中,同步队列作业现在将遵循队列连接或作业的“提交后”配置。
速率限制
每秒速率限制
影响性:中等
Laravel 11 支持每秒速率限制,而不是局限于每分钟粒度。您应该注意与此更改相关的各种潜在中断性变更。
GlobalLimit
类构造函数现在接受秒而不是分钟。此类未记录在案,通常不会由应用程序使用:
php
new GlobalLimit($attempts, 2 * 60);
Limit
类构造函数现在接受秒而不是分钟。此类的所有记录用法仅限于静态构造函数,例如 Limit::p erMinute
和 Limit::p erSecond
。但是,如果要手动实例化此类,则应更新应用程序以向类的构造函数提供秒数:
php
new Limit($key, $attempts, 2 * 60);
Limit
类的 decayMinutes
属性已重命名为 decaySeconds
,现在包含秒而不是分钟。
和 Illuminate\Queue\Middleware\ThrottlesExceptions
Illuminate\Queue\Middleware\ThrottlesExceptionsWithRedis
类构造函数现在接受秒而不是分钟:
php
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 的迁移发布到您的应用程序:
shell
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 的迁移发布到您的应用程序:
shell
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 的迁移发布到您的应用程序:
shell
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 的迁移发布到您的应用程序:
shell
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 的迁移发布到您的应用程序:
shell
php artisan vendor:publish --tag=telescope-migrations
Spatie Once 套餐
影响性:高
Laravel 11 现在提供了自己的 once
函数,以确保给定的闭包只执行一次。因此,如果您的应用程序依赖于 spatie/once
包,则应将其从应用程序的 composer.json
文件中删除以避免冲突。
杂项
我们还鼓励您查看 laravel/laravel
GitHub 存储库中的更改。虽然其中许多更改不是必需的,但您可能希望使这些文件与您的应用程序保持同步。本升级指南将介绍其中一些更改,但其他更改(例如对配置文件或注释的更改)则不会介绍。您可以使用 GitHub 比较工具轻松查看更改,并选择哪些更新对您很重要。