# 升级指南
- [从 6.x 升级到 7.0](#upgrade-7.0)
## 高影响变化
- [Symfony 5 相关更新](#symfony-5-related-upgrades)
- [认证脚手架](#authentication-scaffolding)
- [日期序列化](#date-serialization)
## 中影响变化
- [`Blade::component` 方法](#the-blade-component-method)
- [Blade 组件 & "Blade X"](#blade-components-and-blade-x)
- [工厂类型](#factory-types)
- [表单验证 `different` 验证规则](#the-different-rule)
- [测试 `assertSee` 断言](#assert-see)
## 从 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](https://github.com/laravel/browser-kit-testing/blob/master/UPGRADE.md)
- [Envoy v2.0](https://github.com/laravel/envoy/blob/master/UPGRADE.md)
- [Horizon v4.0](https://github.com/laravel/horizon/blob/master/UPGRADE.md)
- [Nova v3.0](https://nova.laravel.com/releases)
- [Scout v8.0](https://github.com/laravel/scout/blob/master/UPGRADE.md)
- 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存储接口 `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" 过程中执行逻辑的地方。如果你的模型已包含了相同名字的方法,你将需要重命名你的方法以避免冲突。
#### 日期序列化
**受影响可能性:高**
在 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');
}
> {tip} 该更改仅影响序列化为数组和 JSON 的模型和模型集合,对数据库中的日期没有影响。
#### 工厂类型
**受影响可能性:中**
Laravel 7 移除了「工厂类型」特性。该特性自 2016 年十月起已未被文档提及。如果你仍在使用此特性,你应该升级至 [工厂状态](/docs/{{version}}/database-testing#factory-states) 以提供更大的灵活性。
#### `getOriginal` 方法
**受影响可能性:低**
`$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` 配置文件](https://github.com/laravel/laravel/blob/develop/config/mail.php) 的结构并更新文件。
#### 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` 实例。
**唯一路由名称**
尽管官方从未正式声明,之前版本的 Laravel 允许你定义同名的两个不同路由,在 Laravel 7 中,这样已经行不通了,你需要为每个路由设置唯一的名称。带有重复名称的路由可能会在多个领域导致异常。
### Session
#### `array` Session 驱动
**受影响可能性:低**
`array` Session 驱动存储的数据现在可于当前请求中访问。过去,`array` Session 中存储的数据无法被当前请求访问。
### 测试
#### `assertSee` 断言
**受影响可能性:中**
`TestResponse` 类中的 `assertSee` 及 `assertDontSee` 断言将会自动转换值。你不需再继续手动转换传递给这些断言的值。
### 验证
#### `different` 规则
**受影响可能性:中**
`different` 规则如今将会在其中一个参数缺失时失败。
### 其他
我们还鼓励您查看 `laravel/laravel` [GitHub 仓库](https://github.com/laravel/laravel) 代码更新日志。 尽管许多更新不是必须的,但您可能希望将这些文件与您的应用程序保持一致。其中的一些更新已经在这篇升级指南中覆盖到了,但是还有很多其他的小更新比如配置文件或注释的微调,就不会一一指出。你可以通过 [GitHub comparison tool](https://github.com/laravel/laravel/compare/6.x...master) 轻松查看变更,以便选择那些对你而言更为重要的更新。