[ Laravel 5.7 文档 ] 序言 —— 升级指南

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

注：本文档演示的是从 5.6 升级到 5.7

更新依赖

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

当然，不要忘了检查应用所使用的第三方扩展包是否支持 Laravel 5.7，如果需要升级的话也要更新。

App

register 方法

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

/**
 * Register a service provider with the application.
 *
 * @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 修复，不过，出于谨慎考虑，这会被列作一个重要更新，如果你对此存疑，可以到 这里 提交 pull request。

认证

Authenticate 中间件

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

/**
 * Determine if the user is logged in to any of the given guards.
 *
 * @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 作为第一个参数，如果你重写了这个方法，需要更新方法签名：

/**
 * Get the response for a successful password reset.
 *
 * @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 作为第一个参数，如果你重写了这个方法，需要更新方法签名：

/**
 * Get the response for a successful password reset link.
 *
 * @param  \Illuminate\Http\Request  $request
 * @param  string  $response
 * @return \Illuminate\Http\RedirectResponse|\Illuminate\Http\JsonResponse
 */
protected function sendResetLinkResponse(Request $request, $response)

授权

Gate 契约

raw 方法的可见性从 protected 调整为 public ，此外，该方法声明还被添加到 Illuminate/Contracts/Auth/Access/Gate 契约：

/**
 * Get the raw result from the authorization callback.
 *
 * @param  string  $ability
 * @param  array|mixed  $arguments
 * @return mixed
 */
public function raw($ability, $arguments = []);

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

Blade

or 操作符

Blade 的 or 操作符被移除，因为可以通过 PHP 内置的 ?? 操作符来替代：

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

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

Carbon

Carbon 的「macros」现在直接由 Carbon 库处理，取代了之前通过 Laravel 扩展包处理的方式，我们希望这不会对你现有的代码造成影响，有任何问题， 欢迎向我们反馈 。

集合

split 方法

split 方法被更新为永远按照请求数量对集合进行分组，除非原生集合的条目总数少于请求的分组数，通常，这也会被看作是一个 bug 修复，不过谨慎起见，我们将其列作一个重要的更新。

Cookie

Factory 契约方法签名

Illuminate/Contracts/Cookie/Factory 接口的 make 和 forever 方法签名 被修改了 ，如果你实现了这个接口，需要更新实现类中的这些方法。

数据库

softDeleteTz 迁移方法

表结构构建器的 softDeletesTz 方法现在接收列名作为第一个参数，而 $precision 被调整为第二个参数：

/**
 * Add a "deleted at" timestampTz for the table.
 *
 * @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 参数：

/**
 * Run a select statement and return a single result.
 *
 * @param  string  $query
 * @param  array   $bindings
 * @param  bool  $useReadPdo
 * @return mixed
 */
public function selectOne($query, $bindings = [], $useReadPdo = true);

/**
 * Run a select statement against the database.
 *
 * @param  string  $query
 * @param  array   $bindings
 * @param  bool  $useReadPdo
 * @return array
 */
public function select($query, $bindings = [], $useReadPdo = true);

此外， cursor 方法还被添加到这个契约中：

/**
 * Run a select statement against the database and returns a generator.
 *
 * @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_ODBC 驱动：

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

如果这两个驱动都无效，Laravel 将使用 PDO_DBLIB 驱动。

调试

Dumper 类

移除了 Illuminate\Support\Debug\Dumper 和 Illuminate\Support\Debug\HtmlDumper 类以便于使用 Symfony 的原生变量打印类：

Symfony\Component\VarDumper\VarDumper 和 Symfony\Component\VarDumper\Dumper\HtmlDumper 。

Eloquent

latest / oldest 方法

Eloquent 查询构建器的 latest 和 oldest 方法被更新为识别可能会被设置到 Eloquent 模型类上的 "created at" 时间戳字段。

wasChanged 方法

Eloquent 模型的修改会在触发 updated 模型事件之前在 wasChanged 方法中生效，如果你对此有疑问， 可以向我们反馈 。

PostgreSQL 指定的浮点值

PostgreSQL 现在支持浮点值 Infinity 、 -Infinity 和 NaN 。在 Laravel 5.7 之前，这些值在 Eloquent 将数据类型转化为 float 、 double 或 real 时都会被转化为 0 。

在 Laravel 5.7 中，这些值将会被转化为相应的 PHP 常量 INF 、 -INF 和 NAN 。

邮箱验证

如果你选择使用 Laravel 5.7 提供的 邮箱验证服务 ，需要添加额外的脚手架代码到应用，首先，添加 VerificationController 到应用： App\Http\Controllers\Auth\VerificationController 。

你还需要验证视图存根文件，这个视图文件位于 resources/views/auth/verify.blade.php ，你可以在 GitHub 仓库 中查看视图内容。

最后，当调用 Auth::routes 方法时，需要传递 verify 选项到方法：

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

文件系统

Filesystem 契约方法

Illuminate\Contracts\Filesystem\Filesystem 契约新增了 readStream 和 writeStream 方法。如果你实现了这个接口，需要将这些方法添加到实现类中。

邮件

Mailable 动态变量风格

动态传递到邮件视图的变量现在可以 自动转化为驼峰风格 ，这使得邮件动态变量和动态视图变量的行为得以保持一致，动态邮件变量并不是可以文档化的 Laravel 特性，所以对应用的影响微乎其微。

路由

Route::redirect 方法

Route::redirect 方法现在会在重定向时返回 302 状态码，而 permanentRedirect 方法则会返回 301 状态码：

// Return a 302 redirect...
Route::redirect('/foo', '/bar');

// Return a 301 redirect...
Route::redirect('/foo', '/bar', 301);

// Return a 301 redirect...
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);

// Prior Behavior...
['person' => ['name' => 'Taylor', 'job' => 'Developer']]

// New Behavior...
['person' => ['name' => 'Taylor']]

Validator 契约

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

/**
 * Run the validator's rules against its data.
 *
 * @return array
 */
public function validate();

如果你实现了这个接口，需要在实现类中添加该方法。

杂项

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