hyperf/docs/zh-hk/upgrade/2.2.md

# 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)