升级指南
高影响变化
中影响变化
从 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
类中的 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('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
参数。如果要覆盖此方法,则应更新方法以接受此参数。
最后,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 邮件租金已被移除。
队列
已被弃用的 —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
类中的 assertSee
及 assertDontSee
断言将会自动转换值。你不需再继续手动转换传递给这些断言的值。
验证
different 规则
受影响可能性:中
different
规则如今将会在其中一个参数缺失时失败。
其他
我们还鼓励您查看 laravel/laravel
GitHub 仓库 代码更新日志。 尽管许多更新不是必须的,但您可能希望将这些文件与您的应用程序保持一致。其中的一些更新已经在这篇升级指南中覆盖到了,但是还有很多其他的小更新比如配置文件或注释的微调,就不会一一指出。你可以通过 GitHub comparison tool 轻松查看变更,以便选择那些对你而言更为重要的更新。
本文章首发在 LearnKu.com 网站上。
本文中的所有译文仅用于学习和交流目的,转载请务必注明文章译者、出处、和本文链接 我们的翻译工作遵照 CC 协议,如果我们的工作有侵犯到您的权益,请及时联系我们。
Laravel China 社区:https://learnku.com/docs/laravel/7.x/upgrade/7445