升级指南

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

PHP

更新依赖

此外，如果你使用下以下官方扩展包，也要升级它们到最新版本：

• Dusk (升级到 ~3.0)
• Passport (升级到 ~5.0)
• Scout (升级到 ~4.0)

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

Symfony 4

Laravel 底层使用的所有 Symfony 组件都已经升级到 Symfony ~4.0 版本。如果你在应用代码中使用了 Symfony 组件，需要查看 Symfony 更新日志以确认是否需要修改代码。

PHPUnit

需要更新应用的 phpunit/phpunit 依赖到 ~7.0。

数组

Arr::wrap 方法

在 Laravel 5.6 中，传递 null 到 Arr::wrap 方法将会返回空数组。

Artisan

optimize 命令

之前版本中废弃的 optimize 命令已经被彻底移除。由于 PHP 自身的性能优化，optimize 命令已经不能给应用提供显著的性能提升，所以，你需要从 composer.json 文件的 scripts 部分移除 php artisan optimize。

Blade

HTML 实体编码

在之前版本的 Laravel 中，Blade 不会对 HTML 实体进行双重编码。这并不是底层 htmlspecialchars 函数的默认行为，而且会在渲染内容或传递内联 JSON 内容到 JavaScript 框架时导致预期之外的结果。

在 Laravel 5.6 中，Blade 以及辅助函数 e 默认会对特殊字符进行双重编码，从而与 PHP 底层 htmlspecialchars 函数的默认行为保持一致。如果你想要维持不进行双重编码的旧状，可以使用 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 新增方法

MigrationRepositoryInterface 中新增了一个 getMigrationsBatches 方法。如果非常不巧你正在自定义该类的实现，需要添加这个方法的实现。你可以以框架的默认实现作为示例。

Eloquent

getDateFormat 方法

getDateFormat 方法的可见性从 protected 调整为 public。

哈希

新配置文件

所有哈希配置现在位于独立的 config/hashing.php 配置文件。你可以拷贝一份默认配置文件到你的应用。大多数情况下，我们都会将 bcrypt 驱动作为默认驱动。不过，也支持 argon。

辅助函数

e

在之前版本的 Laravel 中，Blade （以及辅助函数 e）不会对 HTML 实体进行双重编码。这并不是底层 htmlspecialchars 函数的默认行为，而且会在渲染内容或传递内联 JSON 内容到 JavaScript 框架时导致预期之外的结果。

在 Laravel 5.6 中，Blade 以及辅助函数 e 默认会对特殊字符进行双重编码，从而与 PHP 底层 htmlspecialchars 函数的默认行为保持一致。如果你想要维持不进行双重编码的旧状，可以传递 false 作为第二个参数到 e 函数：

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

日志

新配置文件

所有的日志配置现在都存放在独立的 config/logging.php 配置文件。你可以拷贝一份默认的配置文件到你的应用然后基于应用需要进行设置。

log 和 log_level 配置项都可以从配置文件 config/app.php 里移除了。

configureMonologUsing 方法

如果你在使用 configureMonologUsing 方法为应用自定义 Monolog 实例，现在需要创建一个 custom 日志频道。更多关于如何创建自定义频道的信息，可以查看完整的日志文档。

日志 Writer 类

Illuminate\Log\Writer 类被重命名为 Illuminate\Log\Logger，如果你在应用的某个类中对这个类进行了显式的类型提示作为依赖注入，需要更新该类的引用为新的类名。或者，作为替代方案，你可以考虑将类型提示调整为标准的 Psr\Log\LoggerInterface 接口。

Illuminate\Contracts\Logging\Log 接口

该接口已经被移除，因为它和 Psr\Log\LoggerInterface 接口完全重合，需要将引用它的地方都调整为 Psr\Log\LoggerInterface 接口。

邮件

withSwiftMessage 回调

在之前版本的 Laravel 中，使用 withSwiftMessage 注册的 Swift 消息自定义回调函数在内容已经被编码并添加到消息后被调用。这些回调现在在内容被添加前调用，从而允许你自定义编码以及其他消息选项。

分页

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
{
    /**
     * Bootstrap any application services.
     *
     * @return void
     */
    public function boot()
    {
        Paginator::useBootstrapThree();
    }
}

资源

original 属性

资源响应的 original 属性现在被设置为原始模型而不是 JSON 字符串/数组。这样在测试中就可以更好地检查响应的模型。

路由

返回新创建的模型

从路由中直接返回新创建的 Eloquent 模型时，响应状态码由 200 调整为 201，如果应用的任意相应测试显式期望 200 状态码，那么需要将它们修改为 201。

信任代理

由于信任代码功能使用的底层 Symfony HttpFoundation 有改动，所以必须微调 App\Http\Middleware\TrustProxies 中间件。

$headers 属性之前是个数组，现在是一个接收几个不同值的属性。例如，要信任所有转发头，需要像这样更新 $headers 属性：

use Illuminate\Http\Request;

/**
 * The headers that should be used to detect proxies.
 *
 * @var string
 */
protected $headers = Request::HEADER_X_FORWARDED_ALL;

更多关于 $headers 变量值的信息可以查看完整的信任代理文档。

验证

ValidatesWhenResolved 接口

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

杂项

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