升级指南

声明：本指南适用于从 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.1，phpunit/phpunit 依赖版本为 ^8.5，laravel/tinker 依赖版本为 ^2.0，以及 facade/ignition 依赖版本为 ^2.0。

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

• Browser Kit Testing v6.0
• Envoy v2.0
• Horizon v4.0
• Nova v3.0
• Scout v8.0
• UI v2.0（无需更改）

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

Symfony 5 相关升级

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

首先，App\Exceptions\Handler 类的 report 和 render 方法需要调整为接收 Throwable 接口实例而不是 Exception 实例：

use Throwable;

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

然后，修改 session 配置文件的 secure 选项，支持默认值 null，并新增默认值为 lax 的 same_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 内置的标签组件功能，可以在 AppServiceProvider 的 boot 方法中调用 withoutComponentTags 方法：

use Illuminate\Support\Facades\Blade;

Blade::withoutComponentTags();

Eloquent

addHidden/addVisible 方法

无文档的 addHidden 和 addVisible 被移除，取而代之的是 makeHidden 和 makeVisible 方法。

booting/booted 方法

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

日期序列化

Laravel 7 在 Eloquent 模型类中调用 toArray 和 toJson 方法时，使用了一个新的日期序列化格式。框架现在使用 Carbon 的 toJson 方法为格式化日期，该方法会生成一个兼容 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 类中的 assertSee 和 assertDontSee 断言现在会自动对值进行转义，如果你之前手动转义过传递到这些断言的值，以后不必这么做了。如果你需要断言未转义的值，可以传递 false 作为第二个参数到该方法。

验证

different 规则

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

其它

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