* * * * * [TOC] ## 从 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 变更日志](https://github.com/symfony/symfony/blob/master/UPGRADE-4.0.md)。 #### 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` 配置文件中。 你应该在程序中复制一份 [默认配置文件](https://github.com/laravel/laravel/blob/develop/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` 配置文件中，你应该在你自己的应用程序中放置一个[默认配置文件](https://github.com/laravel/laravel/blob/develop/config/logging.php)的副本，并根据你的应用程序的需要进行调整修改。 `log` 和 `log_level` 配置选项可以在 `config / app.php` 配置文件中删除。 #### `configureMonologUsing` 方法 如果你使用 `configureMonologUsing` 方法为应用程序自定义 Monolog 实例，你现在应该创建一个 `custom` 日志通道。有关如何创建自定义频道的更多信息，请查看 [full logging documentation](https://www.kancloud.cn/tonyyu/laravel_5_6/786183#_181)。 #### 日志类 `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` 属性 [资源响应](https://www.kancloud.cn/tonyyu/laravel_5_6/786276) 的 `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](https://www.kancloud.cn/tonyyu/laravel_5_6/786157#_422) 的完整文档 。 ### 验证 #### `ValidatesWhenResolved` 接口 为了避免和 `$request->validate()` 方法冲突， `ValidatesWhenResolved` 接口 / trait 的 `validate` 方法已被改名为 `validateResolved` 。 ### 其它 我们同样鼓励你去翻阅 `laravel/laravel` [GitHub 仓库](https://github.com/laravel/laravel) 中的修改记录。 虽然很多修改不是必需的，但你可能希望这些文件与你的应用程序同步。本升级指南中只介绍了部分修改，而其它像修改配置文件或注释等修改则不会介绍。你可以使用 [GitHub 比较工具](https://github.com/laravel/laravel/compare/5.5...master) 很轻松的查看这些修改并选择对你重要的更新。