# 2.2 升级指南

2.2 版本主要增加了 `PHP 8` 的适配，支持原生注解。

## 修改 Hyperf 组件版本

直接将 `composer.json` 中的 `hyperf/*` 统一修改为 `2.2.*` 即可。

> hyperf/engine 不跟随框架版本号，故不需要修改

另外，我们可以执行 `composer require "hyperf/ide-helper:2.2.*" --dev` 安装 `hyperf/ide-helper`，此组件可以帮助我们在使用原生注解时，提示注解可以设置的参数。

后面只需要执行 `composer update -o`，就可以正常完成升级了。

## 修改单测脚本

增加选项 `--prepend test/bootstrap.php` 

```json
{
    "scripts": {
        "test": "co-phpunit --prepend test/bootstrap.php -c phpunit.xml --colors=always"
    }
}
```

## 安装 pcntl 扩展

新版本的注解扫描使用了 `pcntl` 扩展，所以请先确保您的 `PHP` 安装了此扩展。

```shell
php --ri pcntl

pcntl

pcntl support => enabled
```

> 当开启 `grpc` 的时候，需要添加 `grpc.enable_fork_support= 1;` 到 `php.ini` 中，以支持开启子进程。

## AMQP

> 使用到 AMQP 的用户请注意，没有的可忽略此小节。

因为 `AMQP` 组件全线升级，支持多路复用，所以配置上也有一定更改。请按照以下最新的配置，酌情修改。

```php
<?php

return [
    'default' => [
        'host' => env('AMQP_HOST', 'localhost'),
        'port' => (int) env('AMQP_PORT', 5672),
        'user' => env('AMQP_USER', 'guest'),
        'password' => env('AMQP_PASSWORD', 'guest'),
        'vhost' => env('AMQP_VHOST', '/'),
        'concurrent' => [
            'limit' => 1,
        ],
        'pool' => [
            // 同时开启的连接数
            // 因为新版本连接是支持多路复用的，所以可以用极少的连接数达到很高的并发
            'connections' => 2,
        ],
        'params' => [
            'insist' => false,
            'login_method' => 'AMQPLAIN',
            'login_response' => null,
            'locale' => 'en_US',
            'connection_timeout' => 3,
            'read_write_timeout' => 6,
            'context' => null,
            'keepalive' => true,
            'heartbeat' => 3,
            'channel_rpc_timeout' => 0.0,
            'close_on_destruct' => false,
            // 多路复用中闲置 Channel 的最大值，超过这个数量后，会关闭多余的限制 Channel
            'max_idle_channels' => 10,
        ],
    ],
];

```

## 配置中心

> 使用到 配置中心 的用户请注意，没有的可忽略此小节。

配置中心在该版本进行了完全的重构，请务必仔细重新阅读对应的文档。

统一都需要引入 `hyperf/config-center` 组件，命令如下：

```shell
composer require "hyperf/config-center:~2.2.0"
```

并根据使用的驱动引入对应的驱动依赖组件，如使用到 `Apollo` 则需要引入 `hyperf/config-apollo` 组件，其余驱动类似。

同时配置中心相关的所有配置信息已全部集合到了 `config/autoload/config_center.php` 中，请根据新的配置结构进行对应的配置，没有该文件可以通过执行 `php bin/hyperf.php vendor:publish hyperf/config-center` 命令来创建。

## 服务中心

使用 `hyperf/service-gonvernace` 组件的用户，因 `consul` 适配器已经从此组件中剥离，新版本下需额外引入 `hyperf/service-governance-consul` 组件，命令如下：

```shell
composer require "hyperf/service-governance-consul:~2.2.0"
```

使用到 `nacos` 作为服务中心驱动的用户则需要引入 `hyperf/service-governance-nacos` 组件，命令如下：

```shell
composer require "hyperf/service-governance-nacos:~2.2.0"
```

## php-cs-fixer

如果不需要升级 `php-cs-fixer` 到 `3.0` 版本，则可以忽略此小节

1. 修改版本号

```
"friendsofphp/php-cs-fixer": "^3.0"
```

2. 重名命 .php_cs 文件

重名命为 `.php-cs-fixer.php` 并根据以下变更记录，修改对应代码

```diff
- return PhpCsFixer\Config::create()
+ return (new PhpCsFixer\Config())

- 'commentType' => 'PHPDoc',
+ 'comment_type' => 'PHPDoc',
```

## PHP 7.3 版本对 DI 的兼容性有所下降

> 使用高版本 PHP 的用户可以忽略此小节。

在 `2.0` - `2.1` 版本时，为了实现 `AOP` 作用于非 `DI` 管理的对象（如 `new` 关键词实例化的对象时），底层实现采用了 `BetterReflection` 组件来实现相关功能，带来新的编程体验的同时，也带来了一些很难攻克的问题，如下:

- 无扫描缓存时项目启动很慢
- 特殊场景下 `Inject` 和 `Value` 不生效
- `BetterReflection` 尚未支持 PHP 8 (截止 2.2 发版时)

在新的版本里，弃用了 `BetterReflection` 的应用，采用了 `子进程扫描` 的方式来解决以上这些痛点，但在低版本的 `PHP` 中也有一些不兼容的情况：

使用 `PHP 7.3` 启动应用后遇到类似如下错误：

```bash
PHP Fatal error:  Interface 'Hyperf\Signal\SignalHandlerInterface' not found in vendor/hyperf/process/src/Handler/ProcessStopHandler.php on line 17

PHP Fatal error:  Interface 'Symfony\Component\Serializer\SerializerInterface' not found in vendor/hyperf/utils/src/Serializer/Serializer.php on line 46
```

此问题是由于在 `PHP 7.3` 中通过 `子进程扫描` 的方式去获取反射，在某个类中实现了一个不存在的 `Interface` ，就会导致抛出 `Interface not found` 的异常，而高版本的 `PHP` 则不会。

解决方法为创建对应的 `Interface` 并正常引入。上文中的报错解决方法为安装对应所依赖的组件即可。

> 当然，最好还是可以升级到 7.4 或者 8.0 版本

```bash
composer require hyperf/signal

composer require symfony/serializer
```

## 文件系统

> 使用到 文件系统 的用户请注意，没有的可忽略此小节。

Hyperf 从 v2.2 版本开始，将同时支持使用 `League\Flysystem` 组件 `v1.0` 和 `v2.0` 版本。

如果您使用了 `League\Flysystem` 的 `v2.0` 版本，对应的适配器也需要按照下述列表进行调整，具体文档请参考 `文件系统` 章节。

- 阿里云 OSS 适配器

```shell
composer require hyperf/flysystem-oss
```

- S3 适配器

```shell
composer require "league/flysystem-aws-s3-v3:^2.0"
composer require hyperf/guzzle
```

- 七牛适配器

```shell
composer require "overtrue/flysystem-qiniu:^2.0"
```

- 内存适配器

```shell
composer require "league/flysystem-memory:^2.0"
```

- 腾讯云 COS 适配器

> 本适配器基础配置与 `overtrue/flysystem-cos` 组件 `v2.0` 版本略有不同，请根据最新版本配置进行适当修改。

```shell
composer require "overtrue/flysystem-cos:^4.0"
```

## 其他可能导致 BC 的修改

[CHANGED](https://github.com/hyperf/hyperf/blob/2.2/CHANGELOG-2.2.md#changed)
