升级说明

5.7

8.x 7.x 6.x 5.8 5.7 5.6 5.5 5.4 5.3 5.2 5.1

Laravel 5.7 中文文档 /

本文档最新版为 8.x，旧版本可能放弃维护，推荐阅读最新版！

升级指南

「从 5.6 升级到 5.7」

从 5.6 升级到 5.7

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

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

更新依赖

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

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

应用

`register` 方法

影响的可能性：非常低

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

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

Artisan

调度任务链接 & 队列

影响的可能性：低

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

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

认证

`Authenticate` 中间件

影响的可能性：低

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

/**
 * 确认用户是否登录到任何给定的警卫。
 *
 * @param  \Illuminate\Http\Request  $request
 * @param  array  $guards
 * @return void
 *
 * @throws \Illuminate\Auth\AuthenticationException
 */
protected function authenticate($request, array $guards)

`ResetsPasswords` Trait

影响的可能性：低

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

/**
 * 获取重置密码成功的响应。
 *
 * @param  \Illuminate\Http\Request  $request
 * @param  string  $response
 * @return \Illuminate\Http\RedirectResponse|\Illuminate\Http\JsonResponse
 */
protected function sendResetResponse(Request $request, $response)

`SendsPasswordResetEmails` Trait

影响的可能性：低

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

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

授权

The `Gate` 契约

影响的可能性：非常低

raw 方法的可见性从 protected 变成 public。此外，它也被添加到了 Illuminate/Contracts/...：

/**
 * 获取授权回调的结果。
 *
 * @param  string  $ability
 * @param  array|mixed  $arguments
 * @return mixed
 */
public function raw($ability, $arguments = []);

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

Blade

The `or` 操作符

影响的可能性：高

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

// Laravel 5.6...
{{ $foo or 'default' }}

// Laravel 5.7...
{{ $foo ?? 'default' }}

Carbon

影响的可能性：非常低

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

Collections

`split` 函数

影响可能性: 低

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

Cookie

`Factory` 契约方法的参数

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

数据库

`softDeletesTz` 迁移方法

影响可能性: 低

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

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

`ConnectionInterface` 契约

影响可能性: 非常低

Illuminate\Contracts\Database\ConnectionInterface 契约的 select 和 selectOne 函数参数更新为提供新的 $useReadPdo 参数：

/**
 * 执行select语句并返回一条结果.
 *
 * @param  string  $query
 * @param  array   $bindings
 * @param  bool  $useReadPdo
 * @return mixed
 */
public function selectOne($query, $bindings = [], $useReadPdo = true);

/**
 * 在数据库执行select语句.
 *
 * @param  string  $query
 * @param  array   $bindings
 * @param  bool  $useReadPdo
 * @return array
 */
public function select($query, $bindings = [], $useReadPdo = true);

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

/**
 * 通过数据库执行select语句并返回一个生成器.
 *
 * @param  string  $query
 * @param  array  $bindings
 * @param  bool  $useReadPdo
 * @return \Generator
 */
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 驱动:

'sqlsrv' => [
    // ...
    'odbc' => true,
    'odbc_datasource_name' => 'your-odbc-dsn',
],

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

Debug

Dumper 类

影响可能性: 非常低

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

Eloquent

`latest` / `oldest` 方法

影响可能性: 低

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

`wasChanged` 方法

影响可能性: 非常低

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

PostgreSQL 特殊浮点值

影响的可能性：低

PostgreSQL 支持 Infinity, -Infinity 和 NaN 浮点值，在Laravel 5.7 之前的版本，当 Eloquent 模型实例中要转换数据类型的列为 float、 double 或 real 时，会被转换成 0。

而在Laravel 5.7中，这些值会被转换成相应的 PHP 常量 INF 、 -INF 和 NAN。

Email 认证

影响的可能性：可选

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

首先，增加 VerificationController 到你的应用：App\Http\Controllers\Auth\VerificationCont...。

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

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

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

文件系统

`Filesystem` 契约方法

影响的可能性：低

Illuminate\Contracts\Filesystem\File... 契约中增加了 readStream 和 writeStream 方法，如果你正在实现这个接口，请增加这些方法。

Mail

邮件动态传参转换

影响的可能性：中

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

路由

`Route::redirect` 方法

影响的可能性：高

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

// 返回302重定向...
Route::redirect('/foo', '/bar');

// 返回301重定向...
Route::redirect('/foo', '/bar', 301);

// 返回301重定向...
Route::permanentRedirect('/foo', '/bar');

`addRoute` 方法

影响的可能性：低

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

表单验证

嵌套验证数据

影响的可能性：中

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

$data = Validator::make([
    'person' => [
        'name' => 'Taylor',
        'job' => 'Developer'
    ]
], ['person.name' => 'required'])->validate();

dump($data);

// 旧的结果...
['person' => ['name' => 'Taylor', 'job' => 'Developer']]

// 新的结果...
['person' => ['name' => 'Taylor']]

`Validator` Contract

影响的可能性：非常低

Illuminate/Contracts/Validation/Vali... validate 方法：

/**
 * 根据数据运行表单验证规则。
 *
 * @return array
 */
public function validate();

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

其它

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

本文章首发在网站上。

升级说明 5.7 8.x 7.x 6.x 5.8 5.7 5.6 5.5 5.4 5.3 5.2 5.1

升级指南

从 5.6 升级到 5.7

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

更新依赖

应用

register 方法

Artisan

调度任务链接 & 队列

认证

Authenticate 中间件

ResetsPasswords Trait

SendsPasswordResetEmails Trait

授权

The Gate 契约

Blade

The or 操作符

Carbon

Collections

split 函数

Cookie

Factory 契约方法的参数

数据库

softDeletesTz 迁移方法

ConnectionInterface 契约

SQL Server驱动优先级

Debug

Dumper 类

Eloquent

latest / oldest 方法

wasChanged 方法

PostgreSQL 特殊浮点值

Email 认证

文件系统

Filesystem 契约方法

Mail

邮件动态传参转换

路由

Route::redirect 方法

addRoute 方法

表单验证

嵌套验证数据

Validator Contract

其它

升级说明

5.7

8.x 7.x 6.x 5.8 5.7 5.6 5.5 5.4 5.3 5.2 5.1

`register` 方法

`Authenticate` 中间件

`ResetsPasswords` Trait

`SendsPasswordResetEmails` Trait

The `Gate` 契约

The `or` 操作符

`split` 函数

`Factory` 契约方法的参数

`softDeletesTz` 迁移方法

`ConnectionInterface` 契约

`latest` / `oldest` 方法

`wasChanged` 方法

`Filesystem` 契约方法

`Route::redirect` 方法

`addRoute` 方法

`Validator` Contract