升级指南

从 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 方法：

  1. <?php
  3. namespace App\Providers;
  5. use Illuminate\Support\Facades\Blade;
  6. use Illuminate\Support\ServiceProvider;
  8. class AppServiceProvider extends ServiceProvider
  9. {
  10.     /**
  11.      * Bootstrap any application services.
  12.      *
  13.      * @return void
  14.      */
  15.     public function boot()
  16.     {
  17.         Blade::withoutDoubleEncoding();
  18.     }
  19. }

缓存

速率限制器 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 辅助函数：

  1. <?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 方法：

  1. <?php
  3. namespace App\Providers;
  5. use Illuminate\Pagination\Paginator;
  6. use Illuminate\Support\ServiceProvider;
  8. class AppServiceProvider extends ServiceProvider
  9. {
  10.     /**
  11.      *  引导任何应用程序服务。
  12.      *
  13.      * @return void
  14.      */
  15.     public function boot()
  16.     {
  17.         Paginator::useBootstrapThree();
  18.     }
  19. }

资源

original 属性

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

路由

返回新创建的模型

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

可信任代理

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

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

  1. use Illuminate\Http\Request;
  3. /**
  4.  * 应该用来检测代理的头信息。
  5.  *
  6.  * @var string
  7.  */
  8. protected $headers = Request::HEADER_X_FORWARDED_ALL;

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

验证

ValidatesWhenResolved 接口

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

其它

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

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

本文中的所有译文仅用于学习和交流目的，转载请务必注明文章译者、出处、和本文链接
我们的翻译工作遵照 CC 协议，如果我们的工作有侵犯到您的权益，请及时联系我们。