升级指南

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

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

更新依赖

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

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

App

register方法

移除了 Illuminate\Foundation\Applicationregister 方法中未使用的参数 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 方法现在将识别任务类上设置的 queueconnection 属性。

这会被看作是 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 修复,不过谨慎起见,我们将其列作一个重要的更新。

Factory 契约方法签名

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

数据库

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 契约的 selectselectOne 方法签名被更新为容纳新的 $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\DumperIlluminate\Support\Debug\HtmlDumper 类以便于使用 Symfony 的原生变量打印类: Symfony\Component\VarDumper\VarDumperSymfony\Component\VarDumper\Dumper\HtmlDumper

Eloquent

latest/oldest 方法

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

wasChanged 方法

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

PostgreSQL 指定的浮点值

PostgreSQL 现在支持浮点值 Infinity-InfinityNaN。在 Laravel 5.7 之前,这些值在 Eloquent 将数据类型转化为 floatdoublereal 时都会被转化为 0

在 Laravel 5.7 中,这些值将会被转化为相应的 PHP 常量 INF-INFNAN

邮箱验证

如果你选择使用 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 契约新增了 readStreamwriteStream 方法。如果你实现了这个接口,需要将这些方法添加到实现类中。

邮件

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 比较工具 轻松查看变更以便选择那些对你而言更为重要的更新。

上一篇: 新版特性

下一篇: 贡献指南