升级指南

声明:本指南适用于从 Laravel 6.x 升级到 Laravel 7.0

影响较大

  • Symfony 5 相关升级
  • 认证脚手架
  • 日期序列化

中等影响

  • 唯一路由名称
  • CORS 支持
  • Blade::component 方法
  • Blade 组件 &「Blade X」
  • 工厂类型
  • different 验证规则
  • assertSee 断言

升级清单

预计耗时:15分钟

注意:Laravel 7 要求 PHP 版本不能低于 7.2.5。

升级依赖

打开项目根目录下的 composer.json 文件,将 laravel/framework 依赖版本更新为 ^7.0,此外,还要更新 nunomaduro/collision 依赖版本为 ^4.1phpunit/phpunit 依赖版本为 ^8.5laravel/tinker 依赖版本为 ^2.0,以及 facade/ignition 依赖版本为 ^2.0

以下官方提供的扩展包已经将主版本升级为支持 Laravel 7,如果对应扩展包有升级指南的话,请在升级前先阅读相应的升级指南(点击链接即可阅读):

最后,检查项目依赖的其他第三方扩展包,并确保使用的版本支持 Laravel 7。

Symfony 5 相关升级

Laravel 7 将底层依赖的 Symfony 组件升级到了 5.x 版本(新的最低兼容版本),为此,我们需要对项目代码做一些小的调整来兼容 Symfony 的升级。

首先,App\Exceptions\Handler 类的 reportrender 方法需要调整为接收 Throwable 接口实例而不是 Exception 实例:

use Throwable;

public function report(Throwable $exception);
public function render($request, Throwable $exception);

然后,修改 session 配置文件的 secure 选项,支持默认值 null,并新增默认值为 laxsame_site 选项:

'secure' => env('SESSION_SECURE_COOKIE', null),

'same_site' => 'lax',   

认证

认证脚手架

所有的认证脚手架代码都被迁移到 laravel/ui 扩展包,如果你在使用 Laravel 的认证脚手架代码,需要安装这个扩展包的 ^2.0 版本,并且这个扩展包需要在所有环境中安装。如果你之前在 composer.json 文件的 require-dev 中引入了这个扩展包,需要将其移动到 require 部分:

composer require laravel/ui "^2.0"

TokenRepositoryInterface 接口

Illuminate\Auth\Passwords\TokenRepositoryInterface 接口中新增了一个 recentlyCreatedToken 方法声明,如果你实现了这个接口,需要在对应实现类中实现这个方法。

Blade

component 方法

Blade::component 方法现在被重命名为 Blade::aliasComponent,需要在调用该方法的地方调整方法名。

Blade 组件 &「Blade X」

Laravel 7 官方引入了对 Blade「标签组件」的支持,如果你想要禁用 Blade 内置的标签组件功能,可以在 AppServiceProviderboot 方法中调用 withoutComponentTags 方法:

use Illuminate\Support\Facades\Blade;

Blade::withoutComponentTags();

Eloquent

addHidden/addVisible 方法

无文档的 addHiddenaddVisible 被移除,取而代之的是 makeHiddenmakeVisible 方法。

booting/booted 方法

bootingbooted 方法被添加到 Eloquent 以便定义需要在模型「boot」过程中执行的任何逻辑。如果你已经在模型类中定义了同名方法,需要对你的方法进行重命名,以避免冲突。

日期序列化

Laravel 7 在 Eloquent 模型类中调用 toArraytoJson 方法时,使用了一个新的日期序列化格式。框架现在使用 CarbontoJson 方法为格式化日期,该方法会生成一个兼容 ISO-8601 的、包含时区信息和小数秒的日期格式。此外,这个调整可以为客户端日期解析库提供更好地支持与集成。

在此之前,日期会被序列化为形如 2019-12-02 20:01:00 这种格式,而现在序列化之后的日期格式是这样的:2019-12-02T20:01:00.283041Z

如果你想要保持之前的日期格式方式,可以在模型类中重写 serializeDate 方法:

/**
 * Prepare a date for array / JSON serialization.
 *
 * @param  \DateTimeInterface  $date
 * @return string
 */
protected function serializeDate(DateTimeInterface $date)
{
    return $date->format('Y-m-d H:i:s');
}

注意:这个调整只会对模型和模型集合序列化为数组或 JSON 格式产生影响,不会影响日期如何存储到数据库。

工厂类型

Laravel 7 移除了「工厂类型」特性,自 2016 年以来就未对该功能有过任何记录。如果你还在使用这个特性,需要将其升级到工厂状态,后者更加灵活。

getOriginal 方法

$model->getOriginal() 方法现在会遵从定义在模型上的所有类型转化,在此之前,该方法会返回未转化的、原生属性值。如果你想要继续获取原生的、未转化的值,可以使用 getRawOriginal 方法作为替代。

路由绑定

Illuminate\Contracts\Routing\UrlRoutable 接口声明的 resolveRouteBinding 方法现在接收一个 $field 参数,如果你手动实现了这个接口,需要更新对应的实现支持这个参数。

此外,Illuminate\Database\Eloquent\Model 类中的 resolveRouteBinding 方法现在也接收一个 $field 参数,如果你重写过这个方法,需要更新对应的方法支持这个参数。

最后,Illuminate\Http\Resources\DelegatesToResources Trait 的 resolveRouteBinding 方法现在也接收一个 $field 参数,如果你重写了这个方法,需要更新对应的方法支持这个参数。

HTTP

兼容 PSR-7

用于生成 PSR-7 响应的 Zend Diactoros 库已经废弃,如果你在使用这个扩展包提供对 PSR-7 的支持,请安装 nyholm/psr7 扩展包作为替代。此外,还要通过 Composer 安装 symfony/psr-http-message-bridge 扩展包的 ^2.0 版本。

邮件

配置文件更改

在 Laravel 7 中,默认的 mail 配置文件做了调整,引入了 mailers 数组以便支持多邮件驱动。不过,为了保持向后兼容,Laravel 6 格式的配置文件仍然支持。因此,升级到 Laravel 7.x 时不需要对配置文件做任何修改。不过,如果你想要检查新的 mail 配置文件结构是否有效,则需要参照官方示例配置文件进行修改。

Markdown 邮件模板更改

默认的 Markdown 邮件模板进行了全新的设计,此外,Markdown 邮件模板的 promotion 组件已经被移除。

队列

移除已废弃的 --daemon 标记

queue:work 命令中的废弃标记 --daemon 被移除,因为队列工作者现在默认已经是通过守护进程的方式运行。

资源

Illuminate\Http\Resources\Json\Resource

已废弃的 Illuminate\Http\Resources\Json\Resource 类被移除。取而代之的,资源类现在应该继承 Illuminate\Http\Resources\Json\JsonResource 类。

路由

Router getRoutes 方法

路由器的 getRoutes 方法现在返回 Illuminate\Routing\RouteCollectionInterface 实例而不是 Illuminate\Routing\RouteCollection 实例。

唯一路由名称

尽管官方从未正式声明,之前版本的 Laravel 允许你定义同名的两个不同路由,在 Laravel 7 中,这样已经行不通了,你需要为每个路由设置唯一的名称。带有重复名称的路由可能会在多个领域导致异常。

CORS 支持

跨域资源共享(CORS)支持现在被默认集成到 Laravel,如果你在使用第三方 CORS 库,建议现在使用新的 cors 配置文件进行配置

接下来,安装底层 CORS 库作为应用依赖:

composer require fruitcake/laravel-cors

最后,添加 \Fruitcake\Cors\HandleCors::class 中间件到 App\Http\Kernel 里的全局中间件列表。

Session

array Session 驱动

array Session 驱动数据现在会在当前请求中被持久化,在此之前,即使是当前请求中,array 驱动存储的 Session 数据也获取不到。

测试

assertSee 断言

TestResponse 类中的 assertSeeassertDontSee 断言现在会自动对值进行转义,如果你之前手动转义过传递到这些断言的值,以后不必这么做了。如果你需要断言未转义的值,可以传递 false 作为第二个参数到该方法。

验证

different 规则

如果请求中某个指定的参数缺失,different 规则现在会验证失败。

其它

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

上一篇: 新版特性

下一篇: 贡献指南