升级指南

高影响变化

中影响变化

从 6.x 升级到 7.0

预计升级时间:15 分钟

{注意} 我们尝试记录了每个可能的主要变化。由于这些主要变化中的一些是在框架的模糊部分,因此这些变化中的某些部分可能会对应用程序产生实际影响。

需要 Symfony 5

受影响可能性: 高

Laravel 7 将底层的 Symfony 组件更新至 5.x 版本,同时也将成为最低支持版本

需要 PHP 7.2.5

受影响可能性: 低

Laravel 7 需要 PHP 7.2.5 或以上版本。

更新依赖

请在 composer.json 文件中更新 laravel/framework 依赖版本到 ^7.0。与此同时,更新 nunomaduro/collision 依赖版本到 ^4.1, phpunit/phpunit 依赖版本到 ^8.5, 以及 facade/ignition 依赖版本到 ^2.0.

下列官方扩展包已发布对应新版本以适配 Laravel 7。如有需要,请阅读对应的更新说明进行升级:

最后,请仔细检查应用中所用的第三方扩展包以确认是否使用了针对 Laravel 7 适配的版本。

Symfony 5 相关更新

受影响可能性:高

Laravel 7 使用了 5.X 系列的 Symfony 组件。为适应此更新,你的应用程序需要作出一些改变。

首先,App\Exceptions\Handler 类中的 reportrender 方法在此前接受 Exception 实例,如今,它接受 Throwable 接口:

  1. use Throwable;
  2. public function report(Throwable $exception);
  3. public function render($request, Throwable $exception);

其次,请更新你的 session 配置文件中的 secure 选项,从而让其拥有一个值为 null 的默认值。并更新 same_site 的值为 lax

  1. 'secure' => env('SESSION_SECURE_COOKIE', null),
  2. 'same_site' => 'lax',

认证方式

脚手架

影响程度: 高

所有认证方式的脚手架都已移至 laravel/ui 仓库。如果您使用的是 Laravel 的认证脚手架,则应该安装此软件的 ^2.0 发行版:

  1. composer require laravel/ui "^2.0"

Token存储接口 TokenRepositoryInterface

影响程度: 低

Illuminate\Auth\Passwords\TokenRepositoryInterface 中新增了 recentlyCreatedToken 方法。如果需要此接口的自定义实现,则应该在实现中添加此方法。

Blade 模板

component 方法

受影响可能性:中

Blade::component 方法已重命名为 Blade::aliasComponent。请相应地更新该方法的调用。

Blade 组件 & “Blade X”

受影响可能性:中

Laravel 7 引入了 Blade “组件标签” 的第一方支持。如果你希望禁用 Blade 内置的标签组件功能,你可以在 AppServiceProviderboot 方法中调用 withoutComponentTags 方法:

  1. use Illuminate\Support\Facades\Blade;
  2. Blade::withoutComponentTags();

Eloquent

addHidden / addVisible 方法

受影响可能性:低

未被文档提及的 addHiddenaddVisible 方法已被移除。请使用 makeHiddenmakeVisible 方法。

booting / booted 方法

受影响可能性:低

bootingbooted 已被添加至 Eloquent 以提供一个方便地定义在 “Boot” 过程中执行逻辑的地方。如果你的模型已包含了相同名字的方法,你将需要重命名你的方法以避免冲突。

日期序列化

受影响可能性:高

在 Eloquent 模型上使用 toArraytoJson 方法时,Laravel 7 将使用新的日期序列化格式。为了格式化日期以进行序列化,Laravel 将会使用 Carbon 的 toJSON 方法,该方法将生成与 ISO-8601 兼容的日期,包括时区信息及小数秒。此外,该更改提供了更好的支持,并与客户端如期解析库集成。

此前,日期将序列化为以下格式:2020-03-04 16:11:00 。使用新格式进行序列化的日期将显示为:2020-03-04T20:01:00.283041Z

如果你希望继续保持之前所用的格式,你可以重写模型的 serializeDate 方法:

  1. /**
  2. * 为数组 / JSON 序列化准备日期。
  3. *
  4. * @param \DateTimeInterface $date
  5. * @return string
  6. */
  7. protected function serializeDate(DateTimeInterface $date)
  8. {
  9. return $date->format('Y-m-d H:i:s');
  10. }

技巧:该更改仅影响序列化为数组和 JSON 的模型和模型集合,对数据库中的日期没有影响。

工厂类型

受影响可能性:中

Laravel 7 移除了「工厂类型」特性。该特性自 2016 年十月起已未被文档提及。如果你仍在使用此特性,你应该升级至 工厂状态 以提供更大的灵活性。

getOriginal 方法

受影响可能性:低

$model->getOriginal() 方法现在将重视模型中定义的类型转换。此前,此方法返回未被修改的原始属性。如今,如果你希望获取未经修改的原始属性,请使用 getRawOriginal 方法。

路由绑定

影响程度: 低

Illuminate\Contracts\Routing\UrlRoutable 的方法 resolveRouteBinding 现在接受一个 $field 参数。如果您已手动实现此接口,则需要更新其实现。

此外,Illuminate\Database\Eloquent\Model 类的 resolveRouteBinding 方法现在还接受一个 $field 参数。如果要覆盖此方法,则应更新方法以接受此参数。

最后,trait Illuminate\Http\Resources\DelegatesToResourcesresolveRouteBinding 方法现在还接受一个 $field 参数。如果要覆盖此方法,则应更新方法以接受此参数。

HTTP

PSR-7 兼容性

影响程度: 低

不推荐使用 Zend Diactoros 库来生成 PSR-7 响应。如果您将此软件包用于 PSR-7 兼容性,请安装 nyholm/psr7 的 Composer 包。另外,请安装 symfony/psr-http-message-bridge^2.0 发行版Composer包。

邮件

配置文件更改

受影响可能性:可选

为支持多个邮件驱动,Laravel 7 中默认的 mail 配置文件已更改为包含 mailers 数组。然而,为了保持向后兼容性,仍支持 Laravel 6 格式的配置文件。因此,升级到 Laravel 7 时,无需进行任何更改。但是,你可能想要查看 新的 mail 配置文件 的结构并更新文件。

Markdown 邮件模板更新

受影响可能性:低

默认的 Markdown 邮件模板已被更新为更专业及具吸引力的设计。另外,文档未提及的 promotion Markdown 邮件租金已被移除。

队列

已被弃用的 —daemon 标识已被移除

受影响可能性:低

早前弃用的 queue:work 命令的 —daemon 标识已被正式移除。由于队列现在默认以守护进程的方式运行,因此,你不再需要该标识符。

资源

Illuminate\Http\Resources\Json\Resource 类

受影响可能性:低

弃用的 Illuminate\Http\Resources\Json\Resource 类已被正式移除。你的资源应当继承 Illuminate\Http\Resources\Json\JsonResource 类作为替代。

路由

Router getRoutes 方法

受影响可能性:低

路由器(Router)的 getRoutes 方法如今不再返回 Illuminate\Routing\RouteCollection 实例,取而代之的是 Illuminate\Routing\RouteCollectionInterface 实例。

Session

array Session 驱动

受影响可能性:低

array Session 驱动存储的数据现在可于当前请求中访问。过去,array Session 中存储的数据无法被当前请求访问。

测试

assertSee 断言

受影响可能性:中

TestResponse 类中的 assertSeeassertDontSee 断言将会自动转换值。你不需再继续手动转换传递给这些断言的值。

验证

different 规则

受影响可能性:中

different 规则如今将会在其中一个参数缺失时失败。

其他

我们还鼓励您查看 laravel/laravel GitHub 仓库 代码更新日志。 尽管许多更新不是必须的,但您可能希望将这些文件与您的应用程序保持一致。其中的一些更新已经在这篇升级指南中覆盖到了,但是还有很多其他的小更新比如配置文件或注释的微调,就不会一一指出。你可以通过 GitHub comparison tool 轻松查看变更,以便选择那些对你而言更为重要的更新。

本文章首发在 LearnKu.com 网站上。

本文中的所有译文仅用于学习和交流目的,转载请务必注明文章译者、出处、和本文链接 我们的翻译工作遵照 CC 协议,如果我们的工作有侵犯到您的权益,请及时联系我们。

Laravel China 社区:https://learnku.com/docs/laravel/7.x/upgrade/7445