升级指南

从 5.6 升级到 5.7

预计升级时间:10-15分钟

注:我们试图记录每一个可能发生的变化。因为大部分破坏性的变化在框架的内部,这些更改仅有一部分的更改可能影响你的应用。

更新依赖

composer.json 文件中更新 laravel/framework 依赖到 5.7.*

当然,不要忘记检查应用所使用的第三方扩展包是否支持 Laravel 5.7。

应用

register 方法

影响的可能性:非常低

Illuminate\Foundation\Applicationregister 方法中,未使用的参数 options 已经被移出,如果你重写了这个方法,需要更新方法的签名:

  1. /**
  2. * 使用应用程序注册服务提供者。
  3. *
  4. * @param \Illuminate\Support\ServiceProvider|string $provider
  5. * @param bool $force
  6. * @return \Illuminate\Support\ServiceProvider
  7. */
  8. public function register($provider, $force = false);

Artisan

调度任务链接 & 队列

影响的可能性:低

在作业类中,如果一个连接 / 任务没有明确地传递给 job 方法的话,$schedule->job 方法现在将识别任务类上设置 queueconnection 属性。

一般来说,这应该被认为是一个 bug 修复,然而,它被列为一个破坏性的改变。「如果你遇到任何关于这个变化的问题,请告诉我们」。

认证

Authenticate 中间件

影响的可能性:低

Illuminate\Auth\Middleware\Authenticate 中间件的 authenticate 方法会被更新为将 $request 作为第一个参数,如果你在自己的 Authenticate 中间件中重写了这个方法,需要更新中间件方法的签名:

  1. /**
  2. * 确认用户是否登录到任何给定的警卫。
  3. *
  4. * @param \Illuminate\Http\Request $request
  5. * @param array $guards
  6. * @return void
  7. *
  8. * @throws \Illuminate\Auth\AuthenticationException
  9. */
  10. protected function authenticate($request, array $guards)

ResetsPasswords Trait

影响的可能性:低

ResetsPasswords trait 中受保护的方法 sendResetResponse 现在接收 Illuminate\Http\Request 作为第一个参数。如果你覆盖了这个方法,你需要修改方法的签名:

  1. /**
  2. * 获取重置密码成功的响应。
  3. *
  4. * @param \Illuminate\Http\Request $request
  5. * @param string $response
  6. * @return \Illuminate\Http\RedirectResponse|\Illuminate\Http\JsonResponse
  7. */
  8. protected function sendResetResponse(Request $request, $response)

SendsPasswordResetEmails Trait

影响的可能性:低

SendsPasswordResetEmails trait 中受保护的方法 sendResetLinkResponse 现在接收 Illuminate\Http\Request 作为第一个参数。如果你覆盖了这个方法,你需要修改方法的签名:

  1. /**
  2. * 获取重置密码成功链接的响应。
  3. *
  4. * @param \Illuminate\Http\Request $request
  5. * @param string $response
  6. * @return \Illuminate\Http\RedirectResponse|\Illuminate\Http\JsonResponse
  7. */
  8. protected function sendResetLinkResponse(Request $request, $response)

授权

The Gate 契约

影响的可能性:非常低

raw 方法的可见性从 protected 变成 public。此外,它也被添加到了 Illuminate/Contracts/Auth/Access/Gate 契约中

  1. /**
  2. * 获取授权回调的结果。
  3. *
  4. * @param string $ability
  5. * @param array|mixed $arguments
  6. * @return mixed
  7. */
  8. public function raw($ability, $arguments = []);

如果你要实现这个接口,你需要把这个方法添加到实现中。

Blade

The or 操作符

影响的可能性:高

Blade 的「or」操作符被移除了,可以使用 PHP 内置的 ?? 操作符替代:

  1. // Laravel 5.6...
  2. {{ $foo or 'default' }}
  3. // Laravel 5.7...
  4. {{ $foo ?? 'default' }}

Carbon

影响的可能性:非常低

Carbon「macros」不再由 Laravel 的扩展库处理,而是直接通过 Carbon 库处理。我们希望这些变化没有对你的代码造成影响,但是如果有问题的话你可以联系我们

Collections

split 函数

影响可能性: 低

split 函数 已经更新为一直返回请求数量分块的个数,除非原始集合的总数小于请求分块的个数.。准确来说, 这是一个之前bug的修复; 但是,这是一个谨慎的改变。

Factory 契约方法的参数

影响可能性: 非常低Illuminate/Contracts/Cookie/Factory 接口的makeforever 方法的参数默认值 有变动. 如果你实现了这个接口的话,你应该更新你的实现方法。

数据库

softDeletesTz 迁移方法

影响可能性: 低

表结构生成器的 softDeletesTz 方法现在接收列名作为第一个参数,而 $precision 字段已经移动到了第二个参数的位置:

  1. /**
  2. * 在表中添加一个 "deleted at" 的时间戳.
  3. *
  4. * @param string $column
  5. * @param int $precision
  6. * @return \Illuminate\Support\Fluent
  7. */
  8. public function softDeletesTz($column = 'deleted_at', $precision = 0)

ConnectionInterface 契约

影响可能性: 非常低

Illuminate\Contracts\Database\ConnectionInterface 契约的 selectselectOne 函数参数更新为提供新的 $useReadPdo 参数:

  1. /**
  2. * 执行select语句并返回一条结果.
  3. *
  4. * @param string $query
  5. * @param array $bindings
  6. * @param bool $useReadPdo
  7. * @return mixed
  8. */
  9. public function selectOne($query, $bindings = [], $useReadPdo = true);
  10. /**
  11. * 在数据库执行select语句.
  12. *
  13. * @param string $query
  14. * @param array $bindings
  15. * @param bool $useReadPdo
  16. * @return array
  17. */
  18. public function select($query, $bindings = [], $useReadPdo = true);

同时, 将 cursor 方法添加到当前契约中:

  1. /**
  2. * 通过数据库执行select语句并返回一个生成器.
  3. *
  4. * @param string $query
  5. * @param array $bindings
  6. * @param bool $useReadPdo
  7. * @return \Generator
  8. */
  9. public function cursor($query, $bindings = [], $useReadPdo = true);

如果你实现了此接口的话,请将此方法添加到您的实现中。

SQL Server驱动优先级

影响可能性: 低

在 Laravel 5.7之前, PDO_DBLIB 驱动是默认的SQL Server PDO 驱动。 这个驱动是被微软反对的. 在Laravel 5.7中,如果 PDO_SQLSRV 驱动可用的话,PDO_SQLSRV 将作为默认的驱动. 或者你可以选择使用 PDO_ODBC 驱动:

  1. 'sqlsrv' => [
  2. // ...
  3. 'odbc' => true,
  4. 'odbc_datasource_name' => 'your-odbc-dsn',
  5. ],

如果这些驱动都不可用, Laravel 将使用 PDO_DBLIB 驱动。

Debug

Dumper 类

影响可能性: 非常低

为了支持Symfony原生的方法dumpers: Symfony\Component\VarDumper\VarDumperSymfony\Component\VarDumper\Dumper\HtmlDumperIlluminate\Support\Debug\DumperIlluminate\Support\Debug\HtmlDumper 方法已被移除。

Eloquent

latest / oldest 方法

影响可能性: 低

Eloquent查询构造器的 latestoldest 方法更新,现在允许通过自定义的"创建时间"的数据库字段对查询的模型镜像排序。 准确来说, 这是一个之前bug的修复; 但是,这是一个谨慎的改变。

wasChanged 方法

影响可能性: 非常低

Eloquent更改wasChanged方法将在 updated模型事件 之前 调用,这一改变现在可用了。准确来说, 这是一个之前bug的修复; 但是,这是一个谨慎的改变。如果你对此更新有任何疑问,请联系我们

PostgreSQL 特殊浮点值

影响的可能性:低

PostgreSQL 支持 Infinity, -InfinityNaN 浮点值,在Laravel 5.7 之前的版本,当 Eloquent 模型实例中要转换数据类型的列为 floatdoublereal 时,会被转换成 0

而在Laravel 5.7中,这些值会被转换成相应的 PHP 常量 INF-INFNAN

Email 认证

影响的可能性:可选

如果你选择使用 Laravel 的 Email 认证服务,需要向你的应用中增加一些手脚架。

首先,增加 VerificationController 到你的应用:App\Http\Controllers\Auth\VerificationController

其次,增加认证视图文件,文件位置在 resources/views/auth/verify.blade.php,视图内容可以从 GitHub 中获取。

最后,在调用 Auth::routes 方法时传递 verify 选项:

  1. Auth::routes(['verify' => true]);

文件系统

Filesystem 契约方法

影响的可能性:低

Illuminate\Contracts\Filesystem\Filesystem 契约中增加了 readStreamwriteStream 方法,如果你正在实现这个接口,请增加这些方法。

Mail

邮件动态传参转换

影响的可能性:中

向邮件视图中动态传递的变量现在会自动转换为"驼峰命名",这使邮件动态变量行为和动态视图变量保持一致。因为动态邮件变量非 Laravel 文档特性,所以对你的应用产生影响的可能性很小。

路由

Route::redirect 方法

影响的可能性:高

Route::redirect 方法现在返回 HTTP 状态码为 302的重定向,新增 permanentRedirect 方法实现 301 重定向。

  1. // 返回302重定向...
  2. Route::redirect('/foo', '/bar');
  3. // 返回301重定向...
  4. Route::redirect('/foo', '/bar', 301);
  5. // 返回301重定向...
  6. Route::permanentRedirect('/foo', '/bar');

addRoute 方法

影响的可能性:低

Illuminate\Routing\Router 类的 addRoute 方法的可见性从 protected 改为 public

表单验证

嵌套验证数据

影响的可能性:中

在以前版本的 Laravel 中, validate 方法对嵌套验证规则返回的结果不正确,在 Laravel 5.7中已修复:

  1. $data = Validator::make([
  2. 'person' => [
  3. 'name' => 'Taylor',
  4. 'job' => 'Developer'
  5. ]
  6. ], ['person.name' => 'required'])->validate();
  7. dump($data);
  8. // 旧的结果...
  9. ['person' => ['name' => 'Taylor', 'job' => 'Developer']]
  10. // 新的结果...
  11. ['person' => ['name' => 'Taylor']]

Validator Contract

影响的可能性:非常低

Illuminate/Contracts/Validation/Validator 契约新增 validate 方法:

  1. /**
  2. * 根据数据运行表单验证规则。
  3. *
  4. * @return array
  5. */
  6. public function validate();

如果你正实现这个接口,请新增此方法。

其它

我们鼓励你翻阅 laravel/laravel GitHub 仓库中的修改记录。虽然很多修改不是必需的,但你可能希望这些文件和你的应用同步。本升级指南中只介绍了部分修改,而其它像配置文件或注释等修改则没有介绍。 你也可以通过 GitHub 比较工具 很轻松的查看这些改变并选择对你重要的更新。

本文章首发在 LearnKu.com 网站上。

本文中的所有译文仅用于学习和交流目的,转载请务必注明文章译者、出处、和本文链接 我们的翻译工作遵照 CC 协议,如果我们的工作有侵犯到您的权益,请及时联系我们。