Laravel 5.6 中文文档

简体中文

English

简体中文

English

主题

升级指南 ​

从 5.6 升级到 5.6.30（安全发布） ​

Laravel 5.6.30 是一个安全版本，建议所有用户立即升级。Laravel 5.6.30 还包含对 cookie 加密和序列化逻辑的重大更改，因此在升级应用程序时请仔细阅读以下说明。

此漏洞只有在您的应用程序加密密钥（APP_KEY 环境变量）被恶意用户访问时才可能被利用。 通常，您的应用程序用户无法访问此值。但是，曾经有权限访问加密密钥的前员工可能会使用该密钥攻击您的应用程序。如果您有理由相信您的加密密钥已落入恶意方手中，您应始终将密钥旋转为新值。

Laravel 5.6.30 禁用了所有 cookie 值的序列化/反序列化。由于所有 Laravel cookies 都是加密和签名的，因此通常认为 cookie 值是安全的，不会被客户端篡改。但是，如果您的应用程序加密密钥落入恶意方手中，该方可能会使用加密密钥制作 cookie 值，并利用 PHP 对象序列化/反序列化固有的漏洞，例如在您的应用程序中调用任意类方法。

禁用所有 cookie 值的序列化将使您的应用程序的所有会话失效，用户需要重新登录应用程序（除非他们设置了 remember_token，在这种情况下，用户将自动登录到新会话）。此外，您的应用程序设置的任何其他加密 cookie 将具有无效值。因此，您可能希望向应用程序添加额外的逻辑，以验证您的自定义 cookie 值是否与预期值列表匹配；否则，您应丢弃它们。

由于此漏洞无法在没有访问您应用程序加密密钥的情况下被利用，我们选择提供一种方法来重新启用加密 cookie 序列化，同时您使应用程序与这些更改兼容。要启用/禁用 cookie 序列化，您可以更改 App\Http\Middleware\EncryptCookies 中间件 的静态 serialize 属性：

php
/**
 * 指示是否应序列化 cookie。
 *
 * @var bool
 */
protected static $serialize = true;
lightbulb

启用加密 cookie 序列化时，如果应用程序的加密密钥被恶意方访问，您的应用程序将容易受到攻击。如果您认为您的密钥可能已落入恶意方手中，您应在启用加密 cookie 序列化之前将密钥旋转为新值。

Dusk 4.0.0 ​

Dusk 4.0.0 已发布，不会序列化 cookies。如果您选择启用 cookie 序列化，您应继续使用 Dusk 3.0.0。否则，您应升级到 Dusk 4.0.0。

Passport 6.0.7 ​

Passport 6.0.7 已发布，带有新的 Laravel\Passport\Passport::withoutCookieSerialization() 方法。一旦您禁用了 cookie 序列化，您应在应用程序的 AppServiceProvider 中调用此方法。

从 5.5 升级到 5.6.0 ​

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

exclamation

我们尝试记录每一个可能的重大更改。由于其中一些重大更改位于框架的偏僻部分，只有一部分更改可能实际影响您的应用程序。

PHP ​

Laravel 5.6 需要 PHP 7.1.3 或更高版本。

更新依赖项 ​

在您的 composer.json 文件中，将 laravel/framework 依赖项更新为 5.6.*，将 fideloper/proxy 依赖项更新为 ^4.0。

如果您正在使用 laravel/browser-kit-testing 包，您应将该包更新为 4.*。

此外，如果您正在使用以下 Laravel 官方包，您应将它们升级到最新版本：

  • Dusk（升级到 ^3.0）
  • Passport（升级到 ^6.0）
  • Scout（升级到 ^4.0）

当然，不要忘记检查您的应用程序使用的任何第三方包，并验证您是否正在使用支持 Laravel 5.6 的正确版本。

Symfony 4 ​

Laravel 使用的所有底层 Symfony 组件已升级到 Symfony ^4.0 发布系列。如果您在应用程序中直接与 Symfony 组件交互，您应查看 Symfony 变更日志。

PHPUnit ​

您应将应用程序的 phpunit/phpunit 依赖项更新为 ^7.0。

数组 ​

Arr::wrap 方法 ​

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

Artisan ​

optimize 命令 ​

先前已弃用的 optimize Artisan 命令已被移除。由于 PHP 本身的最近改进，包括 OPcache，optimize 命令不再提供任何相关的性能优势。因此，您可以从 composer.json 文件中的 scripts 中移除 php artisan optimize。

Blade ​

HTML 实体编码 ​

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

在 Laravel 5.6 中，Blade 和 e 助手将默认对特殊字符进行双重编码。这使这些功能与底层 htmlspecialchars PHP 函数的默认行为保持一致。如果您希望保持先前的防止双重编码的行为，您可以使用 Blade::withoutDoubleEncoding 方法：

php
<?php

namespace App\Providers;

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

class AppServiceProvider extends ServiceProvider
{
    /**
     * 启动任何应用程序服务。
     *
     * @return void
     */
    public function boot()
    {
        Blade::withoutDoubleEncoding();
    }
}

缓存 ​

速率限制器 tooManyAttempts 方法 ​

此方法的未使用的 $decayMinutes 参数已从方法签名中移除。如果您使用自己的实现覆盖此方法，您也应从方法签名中移除该参数。

数据库 ​

形态列的索引顺序 ​

morphs 迁移方法构建的列的索引已反转以提高性能。如果您在某个迁移中使用 morphs 方法，尝试运行迁移的 down 方法时可能会收到错误。如果应用程序仍在开发中，您可以使用 migrate:fresh 命令从头重建数据库。如果应用程序在生产中，您应为 morphs 方法传递显式索引名称。

MigrationRepositoryInterface 方法添加 ​

MigrationRepositoryInterface 中添加了一个新的 getMigrationsBatches 方法。在极不可能的情况下，您定义了此类的自己的实现，您应将此方法添加到您的实现中。您可以查看框架中的默认实现作为示例。

Eloquent ​

getDateFormat 方法 ​

此 getDateFormat 方法现在是 public 而不是 protected。

哈希 ​

新的配置文件 ​

所有哈希配置现在都放在自己的 config/hashing.php 配置文件中。您应在自己的应用程序中放置一份 默认配置文件 的副本。大多数情况下，您应保持 bcrypt 驱动程序作为默认驱动程序。但是，也支持 argon。

助手 ​

e 助手 ​

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

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

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

日志 ​

新的配置文件 ​

所有日志配置现在都放在自己的 config/logging.php 配置文件中。您应在自己的应用程序中放置一份 默认配置文件 的副本，并根据应用程序的需要调整设置。

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

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
<?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 属性更新为以下值：

php
use Illuminate\Http\Request;

/**
 * 应用于检测代理的头。
 *
 * @var int
 */
protected $headers = Request::HEADER_X_FORWARDED_ALL;

有关可用 $headers 值的更多信息，请查看有关 信任代理 的完整文档。

验证 ​

ValidatesWhenResolved 接口 ​

ValidatesWhenResolved 接口/特征的 validate 方法已重命名为 validateResolved，以避免与 $request->validate() 方法冲突。

杂项 ​

我们还鼓励您查看 laravel/laravel GitHub 仓库 中的更改。虽然其中许多更改不是必需的，但您可能希望将这些文件与您的应用程序保持同步。本升级指南中将涵盖其中一些更改，但其他更改，例如配置文件或注释的更改，将不会涵盖。您可以使用 GitHub 比较工具 轻松查看更改，并选择哪些更新对您来说重要。

版权所有 © 2024-2025 laravel.wiki