升级指南

• 从 6.x 升级到 7.0

高影响变化

• Symfony 5 相关更新
• 认证脚手架
• 日期序列化

中影响变化

• Blade::component 方法
• Blade 组件 & “Blade X”
• 工厂类型
• 表单验证 different 验证规则
• 测试 assertSee 断言

从 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 to ^7.0
• nunomaduro/collision to ^4.1
• phpunit/phpunit to ^8.5
• laravel/tinker to ^2.0
• facade/ignition to ^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 使用了 5.X 系列的 Symfony 组件。为适应此更新，你的应用程序需要作出一些改变。

首先，App\Exceptions\Handler 类中的 report 和 render 方法在此前接受 Exception 实例，如今，它接受 Throwable 接口：

use Throwable;

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

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

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

'same_site' => 'lax',

认证方式

脚手架

影响程度: 高

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

composer require laravel/ui "^2.0"

Token存储接口 <code>TokenRepositoryInterface</code>

影响程度: 低

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

Blade 模板

<code>component</code> 方法

受影响可能性：中

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

Blade 组件 & “Blade X”

受影响可能性：中

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

use Illuminate\Support\Facades\Blade;

Blade::withoutComponentTags();

Eloquent

<code>addHidden</code> / <code>addVisible</code> 方法

受影响可能性：低

未被文档提及的 addHidden 及 addVisible 方法已被移除。请使用 makeHidden 及 makeVisible 方法。

<code>booting</code> / <code>booted</code> 方法

受影响可能性：低

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

日期序列化

受影响可能性：高

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

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

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

/**
 * 为数组 / JSON 序列化准备日期。
 *
 * @param  \DateTimeInterface  $date
 * @return string
 */
protected function serializeDate(DateTimeInterface $date)
{
    return $date->format($this->dateFormat ?: 'Y-m-d H:i:s');
}

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

工厂类型

受影响可能性：中

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

<code>getOriginal</code> 方法

受影响可能性：低

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

路由绑定

影响程度: 低

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

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

最后，trait Illuminate\Http\Resources\DelegatesToResources 的 resolveRouteBinding 方法现在还接受一个 $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 邮件组件已被移除。

队列

已被弃用的 <code>--daemon</code> 标识已被移除

受影响可能性：低

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

资源

<code>Illuminate\Http\Resources\Json\Resource</code> 类

受影响可能性：低

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

路由

Router <code>getRoutes</code> 方法

受影响可能性：低

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

唯一路由名称

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

Session

<code>array</code> Session 驱动

受影响可能性：低

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

测试

<code>assertSee</code> 断言

受影响可能性：中

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

验证

<code>different</code> 规则

受影响可能性：中

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

其他

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