升级说明

5.6

11.x 10.x 9.x 8.5 8.x 7.x 6.x 5.8 5.7 5.6 5.5 5.4 5.3 5.2 5.1

Laravel 5.6 中文文档 /

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

升级指南

从 5.5 升级至 5.6.0

从 5.5 升级至 5.6.0

预计升级耗时：10 - 30 分钟

{note} 我们尽量记录每一个可能的破坏性变化。但因为其中一些不兼容变更只存在于框架很不起眼的地方，事实上只有一小部分可能会影响到你的应用程序。

PHP

Laravel 5.6 要求 PHP 7.1.3 或更高。

更新依赖

在 composer.json 文件中将 laravel/framework 更新为 5.6.* 。此外，你还应将 fideloper/proxy 依赖关系更新至 ~4.0。

此外，如果你使用下面的官方 Laravel 包，你应将升级至最新版本：

Dusk (升级至 ~3.0)
Passport (升级至 ~5.0)
Scout (升级至 ~4.0)

当然，不要忘记检查你应用程序的第三方包能否支持 Laravel 5.6。

Symfony 4

所有 Laravel 底层使用到的 Symfony 组件都已经更新至 ~4.0 发布版本。如果你在应用中直接的与 Symfony 组件进行了交互，你应该浏览下 Symfony 变更日志。

PHPUnit

你必须将你应用中依赖的 phpunit/phpunit 更新至 ~7.0 版本。

Arrays

`Arr::wrap` 方法

传递给 Arr::wrap 方法的 null 现在将返回一个空数组。

Artisan

`optimize` 命令

先前被弃用的 optimize Artisan 命令已经被移除。随着 php 对自身和对操作码缓存的改进, optimize 命令已经无法再提供任何性能上的提升。因此你可以将 php artisan optimize 从你的 composer.json 文件的 scripts 选项中移除。

Blade

HTML 实体编码

在以前的 Laravel 版本中，Blade（和 e 全局辅助函数）不会对 HTML 实体进行双重编码。这不是底层 htmlspecialchars 函数的默认行为，在呈现内容或将内联 JSON 内容传递给 JavaScript 框架时可能会导致意外行为。

在 Laravel 5.6 中，Blade 和 e 全局辅助函数默认会对特殊字符进行双重编码。使得这些功能与底层的 htmlspecialchars PHP 函数的默认行为保持一致。如果你想保持以前防止重复编码的行为，你可以使用 Blade::withoutDoubleEncoding 方法：

<?php

namespace App\Providers;

use Illuminate\Support\Facades\Blade;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    /**
     * Bootstrap any application services.
     *
     * @return void
     */
    public function boot()
    {
        Blade::withoutDoubleEncoding();
    }
}

缓存

速率限制器 `tooManyAttempts` 方法

从未使用过的 $decayMinutes 参数已经被在此方法的签名中移除。如果你自己实现重写了此方法，你需要同时在你的方法签名中移除该参数。

数据库

Morph 列的索引命令

为了更好的性能，通过 morphs迁移方法构建列的索引的方式已经被撤消。如果你正在你的迁移中使用 morphs 方法，可能会在试图运行迁移中的 down 方法时接收到一个错误。如果应用保持在开发状态，你可以使用 migrate:fresh 命令重新构建你的数据库。如果已经在线上生产状态，你应该为 morphs 方法传递一个明确的索引名称。

加入 `MigrationRepositoryInterface` 方法

新的方法 getMigrationsBatches 已经被添加到 MigrationRepositoryInterface 。在你正在定义自己的关于该类的实现的极少数的情况下，你应该将此方法添加到你的实现中。作为示例，你可以查看框架中的默认实现。

Eloquent

`getDateFormat` 方法

现在 getDateFormat 方法的访问修饰符由 protected 变为了 public 。

哈希

新的配置文件

现在所有的哈希配置文件保存在 config/hashing.php 配置文件中。你应该在程序中复制一份默认配置文件。大部分时候，默认的 bcrypt 驱动已经够用了，然而你也可以使用 argon 驱动。

Helpers

`e` 辅助函数

在 Laravel 的旧版本中，Blade (还有 e 辅助函数) 不会对 HTML 实体进行双重编码。这不是底层 htmlspecialchars 函数的默认行为，并且在呈现内容或将内联 JSON 内容传递给 JavaScript 框架时可能会导致意外行为。

在 Laravel 5.6 中，Blade和 e 辅助函数默认会对特殊字符进行双重编码。这些功能与底层 htmlspecialchars PHP 函数的默认行为保持一致。如果你想保持之前防止双重编码的行为，你可以将 false 作为第二个参数传递给 e 辅助函数：

<?php echo e($string, false); ?>

Logging

新的配置文件

所有的日志配置现在都存放在它自己的 config / logging.php 配置文件中，你应该在你自己的应用程序中放置一个默认配置文件的副本，并根据你的应用程序的需要进行调整修改。

log 和 log_level 配置选项可以在 config / app.php 配置文件中删除。

`configureMonologUsing` 方法

如果你使用 configureMonologUsing 方法为应用程序自定义 Monolog 实例，你现在应该创建一个 custom 日志通道。有关如何创建自定义频道的更多信息，请查看 full logging documentation。

日志类 `Writer`

Illuminate\Log\Writer 类已经被重命名为 Illuminate\Log\Logger 。如果你明确地将此类作为你的应用中的类之一的依赖项，你应该将类引用更新为新名称。或者，二者选一地，你应该强烈考虑用标准化的 Psr\Log\LoggerInterface 接口来代替。

`Illuminate\Contracts\Logging\Log` 接口

因为与 Psr\Log\LoggerInterface 完全重复，这个接口已经被移除。你应该用 Psr\Log\LoggerInterface 接口来代替。

邮件

`withSwiftMessage` 回调

在 Laravel 之前的版本中，使用 withSwiftMessage 方法注册的 Swift 消息定制化回调被称为 after 内容已经被编码并且添加到消息中。现在这些被称为 before 内容回调被添加，它们允许你定制这些编码或者是其他需要的消息选项。

分页

Bootstrap 4

现在分页链接被分页器默认采用 Bootstrap 4 生成。使分页器去生成 Bootstrap 3 的链接，可以在你的 AppServiceProvider 文件的 boot 方法中使用 Paginator::useBootstrapThree 方法：

<?php

namespace App\Providers;

use Illuminate\Pagination\Paginator;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    /**
     *  引导任何应用程序服务。
     *
     * @return void
     */
    public function boot()
    {
        Paginator::useBootstrapThree();
    }
}

资源

`original` 属性

资源响应的 original 属性现在会被设置成原始模型而不是 JSON 字符串或数组。在测试时这会更方便检查响应的模型。

路由

返回新创建的模型

当直接从路由返回一个新创建的 Eloquent 模型时，响应状态现在会被自动设置成 201 而不是 200。如果你有任何应用程序的测试的响应状态确定预期是 200 ，请升级成 201。

可信任代理

由于 Symfony HttpFoundation 的可信任代理功能发生了根本性的改变，因此必须对你的应用下的 App\Http\Middleware\TrustProxies 中间件做轻微地改动。

之前是一个数组的 $headers 属性，现在可以接收几个不同值。例如，要信任所有的转发标题，你可以将你的 $headers 属性更新为以下值：

use Illuminate\Http\Request;

/**
 * 应该用来检测代理的头信息。
 *
 * @var string
 */
protected $headers = Request::HEADER_X_FORWARDED_ALL;

关于更多可用的 $headers 值，请查阅 trusting proxies 的完整文档。

验证

`ValidatesWhenResolved` 接口

为了避免和 $request->validate() 方法冲突， ValidatesWhenResolved 接口 / trait 的 validate 方法已被改名为 validateResolved 。

其它

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

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