hyperf/docs/en/upgrade/2.2.md

2.2 Upgrade Guide

Version 2.2 mainly adds the adaptation of PHP 8 and supports native annotations.

Modify Hyperf component version

Simply change hyperf/* in composer.json to 2.2.*.

hyperf/engine does not follow the framework version number, so no modification is required

In addition, we can execute composer require "hyperf/ide-helper:2.2.*" --dev to install hyperf/ide-helper, this component can help us to prompt the parameters that annotations can set when using native annotations.

After that, you only need to execute composer update -o, and the upgrade can be completed normally.

Modify the single test script

Added option --prepend test/bootstrap.php

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

Install the pcntl extension

The new version of annotation scanning uses the pcntl extension, so make sure your PHP has this extension installed first.

php --ri pcntl

pcntl

pcntl support => enabled

When enabling grpc, you need to add grpc.enable_fork_support= 1; to php.ini to support opening child processes.

AMQP

Attention to users who use AMQP, this section can be ignored if there is none.

Because the AMQP component has been upgraded across the board and supports multiplexing, there are certain changes in the configuration. Please follow the latest configuration below and modify as appropriate.

<?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' => [
            // Number of connections opened at the same time
            // Because the new version of the connection supports multiplexing, it can achieve high concurrency with a very small number of connections
            '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,
            // The maximum value of idle channels in multiplexing. After this number is exceeded, the redundant limit channels will be closed.
            'max_idle_channels' => 10,
        ],
    ],
];

Configuration Center

Users who use the Configuration Center, please note that this section can be ignored if there is none.

The configuration center has been completely refactored in this version, please be sure to re-read the corresponding documentation carefully.

Unity needs to introduce the hyperf/config-center component, the command is as follows:

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

And introduce the corresponding driver dependent components according to the driver used. If you use Apollo, you need to import the hyperf/config-apollo component, and the rest of the drivers are similar.

At the same time, all configuration information related to the configuration center has been collected into config/autoload/config_center.php, please configure according to the new configuration structure, without this file, you can execute php bin/hyperf.php vendor:publish hyperf/config-center command to create.

Service Center

For users who use the hyperf/service-gonvernace component, because the consul adapter has been stripped from this component, the new version needs to add the hyperf/service-governance-consul component. The command is as follows:

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

Users who use nacos as a service center driver need to introduce the hyperf/service-governance-nacos component, the command is as follows:

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

php-cs-fixer

If you do not need to upgrade php-cs-fixer to 3.0 version, you can ignore this section

1. Modify the version number

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

2. Rename the .php_cs file

Rename it to .php-cs-fixer.php and modify the corresponding code according to the following change records

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

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

PHP 7.3 version has decreased DI compatibility

Users of advanced versions of PHP can ignore this section.

In 2.0 - 2.1 versions, in order to implement AOP to act on objects not managed by DI (such as objects instantiated by the new keyword), the underlying implementation uses the BetterReflection component to implement related While bringing a new programming experience, it also brings some difficult problems to overcome, as follows:

• slow project startup without scan cache
• Inject and Value do not take effect in special cases
• BetterReflection does not yet support PHP 8 (as of 2.2 release)

In the new version, the application of BetterReflection is deprecated, and the method of subprocess scanning is adopted to solve the above pain points, but there are also some incompatibilities in the lower version of PHP:

After starting the application with PHP 7.3 I get an error similar to the following:

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

This problem is due to the fact that in PHP 7.3, the reflection is obtained by subprocess scanning, and a non-existing Interface is implemented in a certain class, which will cause an exception of Interface not found to be thrown. Higher versions of PHP do not.

The solution is to create the corresponding Interface and import it normally. The solution to the error reported above is to install the corresponding dependent components.

Of course, it is better to upgrade to version 7.4 or 8.0

composer require hyperf/signal

composer require symfony/serializer

File system

For users who use the file system, please note that if there is no, you can ignore this section.

Starting from v2.2, Hyperf will support both League\Flysystem components v1.0 and v2.0.

If you use the v2.0 version of League\Flysystem, the corresponding adapters also need to be adjusted according to the following list, please refer to the File system chapter for specific documentation.

• Alibaba Cloud OSS adapter

composer require hyperf/flysystem-oss

• S3 adapter

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

• Qiniu Adapter

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

• memory adapter

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

• Tencent Cloud COS Adapter

The basic configuration of this adapter is slightly different from the v2.0 version of the overtrue/flysystem-cos component, please make appropriate modifications according to the latest version configuration.

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

Other modifications that may result in BC

CHANGED