Laravel 7.x 中文文档

简体中文

English

简体中文

English

主题

升级指南 ​

高影响变更 ​

中等影响变更 ​

从 6.x 升级到 7.0 ​

预计升级时间：15 分钟 ​

exclamation

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

Symfony 5 必需 ​

影响可能性：高

Laravel 7 将其底层 Symfony 组件升级到了 5.x 系列，这也是新的最低兼容版本。

PHP 7.2.5 必需 ​

影响可能性：低

新的最低 PHP 版本现在是 7.2.5。

更新依赖 ​

在您的 composer.json 文件中更新以下依赖：

  • laravel/framework 到 ^7.0
  • nunomaduro/collision 到 ^4.1
  • phpunit/phpunit 到 ^8.5
  • laravel/tinker 到 ^2.0
  • facade/ignition 到 ^2.0

以下第一方包有新的主要版本以支持 Laravel 7。如果有，请在升级前阅读它们各自的升级指南：

最后，检查您应用程序使用的任何其他第三方包，并验证您使用的是支持 Laravel 7 的正确版本。

Symfony 5 相关升级 ​

影响可能性：高

Laravel 7 使用了 Symfony 组件的 5.x 系列。为了适应此升级，您的应用程序需要进行一些小的更改。

首先，您的应用程序的 App\Exceptions\Handler 类中的 report、render、shouldReport 和 renderForConsole 方法应接受 Throwable 接口的实例，而不是 Exception 实例：

php
use Throwable;

public function report(Throwable $exception);
public function shouldReport(Throwable $exception);
public function render($request, Throwable $exception);
public function renderForConsole($output, Throwable $exception);

此外，任何在队列作业上实现的 failed 方法应接受 Throwable 实例，而不是 Exception 实例。

接下来，请更新您的 session 配置文件的 secure 选项，使其具有 null 的回退值：

php
'secure' => env('SESSION_SECURE_COOKIE', null),

Symfony Console 是支持 Artisan 的底层组件，期望所有命令返回一个整数。因此，您应该确保任何返回值的命令都返回整数：

php
public function handle()
{
    // 之前...
    return true;

    // 之后...
    return 0;
}

认证 ​

脚手架 ​

影响可能性：高

所有认证脚手架已移至 laravel/ui 仓库。如果您使用 Laravel 的认证脚手架，您应该安装此包的 ^2.0 版本，并且该包应安装在所有环境中。如果您之前将此包包含在应用程序的 composer.json 文件的 require-dev 部分中，您应该将其移至 require 部分：

php
composer require laravel/ui "^2.0"

TokenRepositoryInterface ​

影响可能性：低

Illuminate\Auth\Passwords\TokenRepositoryInterface 接口中添加了一个 recentlyCreatedToken 方法。如果您正在编写此接口的自定义实现，您应该在实现中添加此方法。

Blade ​

component 方法 ​

影响可能性：中等

Blade::component 方法已重命名为 Blade::aliasComponent。请相应地更新对此方法的调用。

Blade 组件 & "Blade X" ​

影响可能性：中等

Laravel 7 包含对 Blade "标签组件" 的第一方支持。如果您希望禁用 Blade 的内置标签组件功能，可以从 AppServiceProvider 的 boot 方法中调用 withoutComponentTags 方法：

php
use Illuminate\Support\Facades\Blade;

Blade::withoutComponentTags();

Eloquent ​

addHidden / addVisible 方法 ​

影响可能性：低

未记录的 addHidden 和 addVisible 方法已被移除。请改用 makeHidden 和 makeVisible 方法。

booting / booted 方法 ​

影响可能性：低

booting 和 booted 方法已添加到 Eloquent 中，以便在模型 "启动" 过程中方便地定义任何逻辑。如果您已经有名为这些的模型方法，您需要重命名您的方法，以免与新添加的方法冲突。

日期序列化 ​

影响可能性：高

Laravel 7 在使用 Eloquent 模型的 toArray 或 toJson 方法时使用新的日期序列化格式。为了格式化序列化的日期，框架现在使用 Carbon 的 toJSON 方法，该方法生成包括时区信息和小数秒的 ISO-8601 兼容日期。此外，此更改提供了更好的支持和与客户端日期解析库的集成。

以前，日期会被序列化为如下格式：2019-12-02 20:01:00。使用新格式序列化的日期将显示为：2019-12-02T20:01:00.283041Z。请注意，ISO-8601 日期始终以 UTC 表示。

如果您希望继续使用以前的行为，可以覆盖模型上的 serializeDate 方法：

php
use DateTimeInterface;

/**
 * 准备用于数组/JSON 序列化的日期。
 *
 * @param  \DateTimeInterface  $date
 * @return string
 */
protected function serializeDate(DateTimeInterface $date)
{
    return $date->format('Y-m-d H:i:s');
}
lightbulb

此更改仅影响模型和模型集合序列化为数组和 JSON。此更改不影响日期在数据库中的存储方式。

工厂类型 ​

影响可能性：中等

Laravel 7 移除了 "工厂类型" 功能。自 2016 年 10 月以来，此功能一直未记录。如果您仍在使用此功能，您应该升级到工厂状态，它提供了更多的灵活性。

getOriginal 方法 ​

影响可能性：低

$model->getOriginal() 方法现在将尊重模型上定义的任何转换和修改器。以前，此方法返回未转换的原始属性。如果您希望继续检索原始、未转换的值，可以使用 getRawOriginal 方法。

路由绑定 ​

影响可能性：低

Illuminate\Contracts\Routing\UrlRoutable 接口的 resolveRouteBinding 方法现在接受一个 $field 参数。如果您手动实现了此接口，您应该更新您的实现。

此外，Illuminate\Database\Eloquent\Model 类的 resolveRouteBinding 方法现在也接受一个 $field 参数。如果您重写了此方法，您应该更新您的方法以接受此参数。

最后，Illuminate\Http\Resources\DelegatesToResources trait 的 resolveRouteBinding 方法现在也接受一个 $field 参数。如果您重写了此方法，您应该更新您的方法以接受此参数。

HTTP ​

PSR-7 兼容性 ​

影响可能性：低

用于生成 PSR-7 响应的 Zend Diactoros 库已被弃用。如果您使用此包进行 PSR-7 兼容性，请安装 nyholm/psr7 Composer 包。此外，请安装 symfony/psr-http-message-bridge Composer 包的 ^2.0 版本。

邮件 ​

配置文件更改 ​

影响可能性：可选

为了支持多个邮件程序，Laravel 7.x 中的默认 mail 配置文件已更改为包含一个 mailers 数组。然而，为了保持向后兼容性，Laravel 6.x 格式的此配置文件仍然受支持。因此，在升级到 Laravel 7.x 时不需要进行更改；但是，您可能希望检查新的 mail 配置文件结构并更新您的文件以反映更改。

此外，MAIL_DRIVER 环境变量已重命名为 MAIL_MAILER。

Markdown 邮件模板更新 ​

影响可能性：中等

默认的 Markdown 邮件模板已更新为更专业和吸引人的设计。此外，未记录的 promotion Markdown 邮件组件已被移除。

由于缩进在 Markdown 中具有特殊意义，Markdown 邮件模板期望未缩进的 HTML。如果您之前发布了 Laravel 的默认邮件模板，您需要重新发布您的邮件模板或手动取消缩进它们：

php
php artisan vendor:publish --tag=laravel-mail --force

Swift Mailer 绑定 ​

影响可能性：低

Laravel 7.x 不再提供 swift.mailer 和 swift.transport 容器绑定。您现在可以通过 mailer 绑定访问这些对象：

php
$swiftMailer = app('mailer')->getSwiftMailer();

$swiftTransport = $swiftMailer->getTransport();

资源 ​

Illuminate\Http\Resources\Json\Resource 类 ​

影响可能性：低

已弃用的 Illuminate\Http\Resources\Json\Resource 类已被移除。您的资源应扩展 Illuminate\Http\Resources\Json\JsonResource 类。

路由 ​

路由器 getRoutes 方法 ​

影响可能性：低

路由器的 getRoutes 方法现在返回 Illuminate\Routing\RouteCollectionInterface 的实例，而不是 Illuminate\Routing\RouteCollection。

唯一路由名称 ​

影响可能性：中等

尽管从未正式记录，但以前的 Laravel 版本允许您定义两个具有相同名称的不同路由。在 Laravel 7 中，这不再可能，您应该始终为您的路由提供唯一的名称。具有重复名称的路由可能会在框架的多个区域中导致意外行为。

CORS 支持 ​

影响可能性：中等

跨域资源共享（CORS）支持现在默认集成。如果您正在使用任何第三方 CORS 库，建议您使用新的 cors 配置文件。

接下来，将底层 CORS 库作为应用程序的依赖项安装：

php
composer require fruitcake/laravel-cors

最后，将 \Fruitcake\Cors\HandleCors::class 中间件添加到您的 App\Http\Kernel 全局中间件列表中。

会话 ​

array 会话驱动 ​

影响可能性：低

array 会话驱动的数据现在在当前请求中是持久的。以前，存储在 array 会话中的数据甚至在当前请求期间也无法检索。

测试 ​

assertSee 断言 ​

影响可能性：中等

TestResponse 类上的 assertSee、assertDontSee、assertSeeText、assertDontSeeText、assertSeeInOrder 和 assertSeeTextInOrder 断言现在将自动转义值。如果您手动转义传递给这些断言的任何值，您不应再这样做。如果您需要断言未转义的值，可以将 false 作为第二个参数传递给方法。

TestResponse 类 ​

影响可能性：低

Illuminate\Foundation\Testing\TestResponse 类已重命名为 Illuminate\Testing\TestResponse。如果您正在扩展此类，请确保更新命名空间。

Assert 类 ​

影响可能性：低

Illuminate\Foundation\Testing\Assert 类已重命名为 Illuminate\Testing\Assert。如果您正在使用此类，请确保更新命名空间。

验证 ​

different 规则 ​

影响可能性：中等

如果请求中缺少指定的参数之一，different 规则现在将失败。

杂项 ​

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

版权所有 © 2024-2025 laravel.wiki