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 

  1. {
  2.     "scripts": {
  3.         "test": "co-phpunit --prepend test/bootstrap.php -c phpunit.xml --colors=always"
  4.     }
  5. }

安装 pcntl 扩展

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

  1. php --ri pcntl
  3. pcntl
  5. pcntl support => enabled

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

AMQP

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

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

  1. <?php
  3. return [
  4.     'default' => [
  5.         'host' => env('AMQP_HOST', 'localhost'),
  6.         'port' => (int) env('AMQP_PORT', 5672),
  7.         'user' => env('AMQP_USER', 'guest'),
  8.         'password' => env('AMQP_PASSWORD', 'guest'),
  9.         'vhost' => env('AMQP_VHOST', '/'),
  10.         'concurrent' => [
  11.             'limit' => 1,
  12.         ],
  13.         'pool' => [
  14.             // 同时开启的连接数
  15.             // 因为新版本连接是支持多路复用的，所以可以用极少的连接数达到很高的并发
  16.             'connections' => 2,
  17.         ],
  18.         'params' => [
  19.             'insist' => false,
  20.             'login_method' => 'AMQPLAIN',
  21.             'login_response' => null,
  22.             'locale' => 'en_US',
  23.             'connection_timeout' => 3,
  24.             'read_write_timeout' => 6,
  25.             'context' => null,
  26.             'keepalive' => true,
  27.             'heartbeat' => 3,
  28.             'channel_rpc_timeout' => 0.0,
  29.             'close_on_destruct' => false,
  30.             // 多路复用中闲置 Channel 的最大值，超过这个数量后，会关闭多余的限制 Channel
  31.             'max_idle_channels' => 10,
  32.         ],
  33.     ],
  34. ];

配置中心

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

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

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

  1. 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 组件，命令如下：

  1. composer require "hyperf/service-governance-consul:~2.2.0"

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

  1. composer require "hyperf/service-governance-nacos:~2.2.0"

php-cs-fixer

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

  1. 修改版本号
  1. "friendsofphp/php-cs-fixer": "^3.0"
  1. 重名命 .php_cs 文件

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

  1. - return PhpCsFixer\Config::create()
  2. + return (new PhpCsFixer\Config())
  4. - 'commentType' => 'PHPDoc',
  5. + '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 启动应用后遇到类似如下错误：

  1. PHP Fatal error:  Interface 'Hyperf\Signal\SignalHandlerInterface' not found in vendor/hyperf/process/src/Handler/ProcessStopHandler.php on line 17
  3. 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 版本

  1. composer require hyperf/signal
  3. composer require symfony/serializer

文件系统

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

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

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

  • 阿里云 OSS 适配器
  1. composer require hyperf/flysystem-oss
  • S3 适配器
  1. composer require "league/flysystem-aws-s3-v3:^2.0"
  2. composer require hyperf/guzzle
  • 七牛适配器
  1. composer require "overtrue/flysystem-qiniu:^2.0"
  • 内存适配器
  1. composer require "league/flysystem-memory:^2.0"
  • 腾讯云 COS 适配器

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

  1. composer require "overtrue/flysystem-cos:^4.0"

其他可能导致 BC 的修改

CHANGED