升级说明

升级指南

从 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 配置文件中,你应该在你自己的应用程序中放置一个默认配置文件的副本,并根据你的应用程序的需要进行调整修改。

loglog_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 网站上。

本文中的所有译文仅用于学习和交流目的,转载请务必注明文章译者、出处、和本文链接
我们的翻译工作遵照 CC 协议,如果我们的工作有侵犯到您的权益,请及时联系我们。
上一篇 下一篇
《L01 基础入门》
我们将带你从零开发一个项目并部署到线上,本课程教授 Web 开发中专业、实用的技能,如 Git 工作流、Laravel Mix 前端工作流等。
《L02 从零构建论坛系统》
以构建论坛项目 LaraBBS 为线索,展开对 Laravel 框架的全面学习。应用程序架构思路贴近 Laravel 框架的设计哲学。
贡献者:12