升级说明

8.x

8.x 7.x 6.x 5.8 5.7 5.6 5.5 5.4 5.3 5.2 5.1

Laravel 8 中文文档 /

升级指南

从 7.x 升级到 8.0

高影响变化

模型工厂
retryAfter 队列方法
timeoutAt 队列属性
默认分页

中影响变化

需要 PHP 7.3.0
失败任务表批处理支持
维护模式更新
assertExactJson 方法

从 7.x 升级到 8.0

预计升级时间：15分钟

注意：我们试图记录所有可能的重大更改。由于其中一些重大更改是框架中晦涩难懂的部分，因此这些更改中只有一部分实际上可能会影响您的应用程序。

需要 PHP 7.3.0

影响的程度：中

Laravel 8 需要 PHP 7.3.0 或以上。

更新依赖

请更新你 composer.json 文件中以下依赖：

guzzlehttp/guzzle to ^7.0.1
facade/ignition to ^2.3.6
laravel/framework to ^8.0
laravel/ui to ^3.0
nunomaduro/collision to ^5.0
phpunit/phpunit to ^9.0

下列官方扩展包已发布对应新版本以适配 Laravel 8。如有需要，请阅读对应的更新说明进行升级：

此外，Laravel安装程序已更新，以支持 composer create-project 和 Laravel Jetstream。所有低于 4.0 的安装程序将在2020年10月之后停止工作。您应尽快将全局安装程序升级到^4.0。

最后，检查应用中的其他第三方依赖包，确保你使用的是适用于 Laravel 8 的版本。

集合

`isset` 方法

影响的程度：小

为了和经典的 PHP 保持一致，Illuminate\Support\Collection 的 offsetExists 方法中的 array_key_exists 已经替换成了 isset。由于这一变化，在处理包含 null 值的集合时，会和以前不同：

$collection = collect([null]);

// Laravel 7.x - true
isset($collection[0]);

// Laravel 8.x - false
isset($collection[0]);

Eloquent

Model Factories

影响的程度: 大

Laravel 的模型工厂已经完全重写为基于类的写法，并且和 7.x 中的写法不兼容。然而，为了简化升级过程，我们发布了一个扩展包 laravel/legacy-factories 可以在 Laravel 8 中继续使用你之前的工厂文件。你可以通过 Composer 安装这个依赖：

composer require laravel/legacy-factories

`Castable` 接口

影响的程度: 小

Castable 接口的 castUsing 方法的入参现在改成了数组。如果你使用了这个接口，你应该相应的更新您的实现代码：

public static function castUsing(array $arguments);

Increment / Decrement 事件

影响的程度: 小

现在，Eloquent 模型实例的 increment 或 Decrement 方法调用时，会触发相关模型的「update」和「save」事件。

事件

`Dispatcher` 契约

影响的程度: 小

Illuminate\Contracts\Events\Dispatcher 契约的 listen 方法的 $listener 参数改成了可选的。这一改动是为了实现通过反射自动检测处理事件类型。如果你使用了这个接口，你应该相应的更新您的实现代码：

public function listen($events, $listener = null);

框架

维护模式更新

受影响可能性：可选

Laravel 的维护模式功能已经在Laravel 8.x 中进行了改进。现在支持预渲染维护模式模板，并且消除了用户在维护模式期间遇到错误的机会。然而，为了支持这一特性, 下面的代码必须添加到你的 public/index.php 文件。这些代码应该直接放在现有的 LARAVEL_START 常量定义下面：

define('LARAVEL_START', microtime(true));

if (file_exists(__DIR__.'/../storage/framework/maintenance.php')) {
    require __DIR__.'/../storage/framework/maintenance.php';
}

管理 `$app` 属性

受影响可能性：低

之前不推荐使用的 Illuminate\Support\Manager 类的 $app 属性已经被移除。如果你依赖这个属性，你应该使用 $container 属性代替。

`elixir` 助手

受影响可能性：低

之前不推荐使用的 elixir 助手已经被移除。仍在使用这个方法的应用推荐升级到 Laravel Mix。

邮件

`sendNow` 方法

受影响可能性：低

之前不推荐使用的 sendNow 方法已经被移除。作为替代，请使用 send 方法。

分页

分页默认值

受影响可能性：高

分页器现在使用 Tailwind CSS framework 作为它的默认风格。若要继续保持使用 Bootstrap，你需要在你的应用的 AppServiceProvider 的 boot 方法中添加如下方法调用：

use Illuminate\Pagination\Paginator;

Paginator::useBootstrap();

队列

`retryAfter` 方法

受影响可能性：高

为了和 Laravel 其他特性保持一致，队列任务，邮件系统，通知，监听器中的 retryAfter 方法和 retryAfter 属性被重命名为 backoff。你应该修改你应用中相关的方法和属性名称。

`timeoutAt` 属性

影响的程度: 大

队列任务，通知，监听器中的 timeoutAt 属性被重命名为 retryUntil。你应该修改你应用中相关的属性名称。

失败任务表批处理支持

影响的程度: 可选

如果你计划使用 Laravel 8 的任务批处理特性，你需要更新你的 failed_jobs 数据表。首先，应该添加一个新的 uuid 列。

use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

Schema::table('failed_jobs', function (Blueprint $table) {
    $table->string('uuid')->after('id')->unique();
});

然后，修改 queue 配置文件中的 failed.driver 配置项的值为 database-uuids。

调度

`cron-expression` 库

影响的程度: 小

Laravel 的 dragonmantank/cron-expression 依赖包已经从 2.x 升级为 3.x。如果你没有直接使用 cron-expression 这个扩展包，你的应用应该不会有什么影响。如果你直接使用了，请查看一下它的更新日志。

会话

`Session` 契约

影响的程度: 低

Illuminate\Contracts\Session\Session 契约增加了一个新的 pull 方法。如果你之前手动实现了这个契约，你应该更新一下你的实现代码。

/**
 * 获取给定键的值，然后忘掉它
 *
 * @param  string  $key
 * @param  mixed  $default
 * @return mixed
 */
public function pull($key, $default = null);

测试

`assertExactJson` 方法

受影响可能性：中

assertExactJson 方法现在需要被比较的数组数值键匹配并且有相同的顺序。如果你希望将 JSON 与数组进行对比，而不要求数值键具有相同的顺序，你可以使用 assertSimilarJson 方法替代之。

验证

数据库规则连接

受影响可能性：低

在执行查询时，unique 和 exists 规则现在遵循 Eloquent 模型指定的连接名（通过模型的 getConnectionName 方法访问）。

其他

我们推荐你查看 laravel/laravel GitHub 仓库的更新日志。尽管许多更新不是必须的，但您可能希望将这些文件与您的应用程序保持一致。其中的一些更新已经包含在这个升级说明中了，但是诸如配置文件和注释的更改可能没有。你可以通过 GitHub comparison tool 轻松查看变更，以便选择那些对你而言更为重要的更新。

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