laravel10升级laravel11升级文档中文版

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

摘录

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


版本

升级指南

高影响变更

中等影响变更

低影响变更

从 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 安装程序,您应该通过 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 方法冲突。

修改列

影响可能性:高

当修改列时,您现在必须显式包含所有您希望在列定义更改后保留的修饰符。任何遗漏的属性都将被删除。例如,为了保留 unsigneddefaultcomment 属性,您必须在更改列时显式调用每个修饰符,即使这些属性已经由之前的迁移分配给列。

例如,假设您有一个迁移创建了一个带有 unsigneddefaultcomment 属性的 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 中,这个迁移将保留列上的 unsigneddefaultcomment 属性。然而,在 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 将在运行任何挂起的迁移之前使用您的应用程序的模式文件“迁移”数据库。

浮点类型

影响可能性:高

doublefloat 迁移列类型已经被重写,以在所有数据库上保持一致。

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

$table->double('amount');

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

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

unsignedDecimalunsignedDoubleunsignedFloat 方法已被移除,因为这些列类型的无符号修饰符已被 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);
    // ...
});

空间类型

影响可能性:低

数据库迁移的空间列类型已经被重写,以在所有数据库上保持一致。因此,您可以从迁移中移除 pointlineStringpolygongeometryCollectionmultiPointmultiLineStringmultiPolygonmultiPolygonZ 方法,并使用 geometrygeography 方法代替:

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

要在 MySQL、MariaDB 和 PostgreSQL 上明确限制存储在列中的值的类型或空间参考系统标识符,您可以将 subtypesrid 传递给方法:

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

PostgreSQL 语法的 isGeometryprojection 列修饰符已相应移除。

移除 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::perMinuteLimit::perSecond。然而,如果您手动实例化这个类,您应该更新您的应用程序,为类的构造函数提供秒:

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

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

Illuminate\Queue\Middleware\ThrottlesExceptionsIlluminate\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

此外,密码授权类型默认情况下已禁用。您可以通过在应用程序的 AppServiceProviderboot 方法中调用 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_sessionencrypt_cookiesvalidate_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 比较工具 轻松查看变更,并选择对您重要的更新。

本帖已被设为精华帖!
本帖由 MArtian 于 1个月前 加精
《L02 从零构建论坛系统》
以构建论坛项目 LaraBBS 为线索,展开对 Laravel 框架的全面学习。应用程序架构思路贴近 Laravel 框架的设计哲学。
《G01 Go 实战入门》
从零开始带你一步步开发一个 Go 博客项目,让你在最短的时间内学会使用 Go 进行编码。项目结构很大程度上参考了 Laravel。
讨论数量: 4

以上为AI翻译,翻译结果感觉还不错

1个月前 评论

laravel 11 默认的表用 sqlite、 我自己的项目用 mysql 会有问题吗 今年的 11 默认带了好几张表,不想和项目表混在一起

1个月前 评论

10都还没有用上11就出来了

1个月前 评论

用了一年的10,前几天下了11,感觉好不习惯

1周前 评论

讨论应以学习和精进为目的。请勿发布不友善或者负能量的内容,与人为善,比聪明更重要!