3.0 Upgrade Guide

• Version 3.0 mainly modifies PHP, the minimum version is 8.0
• The framework removes Doctrine Annotations and uses PHP8 Attributes instead
• The framework adds a large number of member variable type restrictions

Convert all annotations

Note: This step can only be performed under version 2.2

The following script will convert all Doctrine Annotations to PHP8 Attributes.

composer require hyperf/code-generator
php bin/hyperf.php code:generate -D app

Modify all Hyperf component version

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

hyperf/engine does not follow the framework version number, so there is no need to modify it, just make sure it is version ^2.1.0

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

Upgrade the database model

Because the model base class adds type support for member variables, you need to use the following script to upgrade it to the new version.

composer require hyperf/code-generator
php vendor/bin/regenerate-models.php $PWD/app/Model

Logger

monolog/monolog 3.x version uses the new features of PHP8.1, so some classes need to be specially modified

Modify array $record to array|LogRecord $record to be compatible with version 3.x, the sample code is as follows

<?php

declare(strict_types=1);

namespace App\Kernel\Log;

use Hyperf\Context\Context;
use Hyperf\Coroutine\Coroutine;
use Monolog\LogRecord;
use Monolog\Processor\ProcessorInterface;

class AppendRequestIdProcessor implements ProcessorInterface
{
    public const REQUEST_ID = 'log.request.id';

    public function __invoke(array|LogRecord $record)
    {
        $record['extra']['request_id'] = Context::getOrSet(self::REQUEST_ID, uniqid());
        $record['extra']['coroutine_id'] = Coroutine::id();
        return $record;
    }
}

##Command

After the 3.0 version, the command line has an event listener enabled by default, so when a listener listens to the Command event and performs AMQP or other multiplexing logic, the process will not be able to exit.

Solution

• method one:

When executing the command, add the option --disable-event-dispatcher

• Method Two:

Add listener

<?php

declare(strict_types=1);

namespace App\Listener;

use Hyperf\Command\Event\AfterExecute;
use Hyperf\Coordinator\Constants;
use Hyperf\Coordinator\CoordinatorManager;
use Hyperf\Event\Annotation\Listener;
use Hyperf\Event\Contract\ListenerInterface;

#[Listener]
class ResumeExitCoordinatorListener implements ListenerInterface
{
    public function listen(): array
    {
        return [
            AfterExecute::class,
        ];
    }

    public function process(object $event): void
    {
        CoordinatorManager::until(Constants::WORKER_EXIT)->resume();
    }
}

Start the server

Next, you only need to start the server, and you can see the unsuitable code and modify them one by one.

• Added types for AMQP Consumer and Producer member variables
• The process method of the Listener adds a void return type
• Annotation #[CircuitBreaker] changed $timeout parameter to $options.timeout

GRPC

The framework modifies the Http status returned by GRPC Server to be 200 according to the GRPC specification, and the GRPC Server returns the corresponding status code. Upgrade to the 3.x version, otherwise the peer end cannot parse the error normally when the request is abnormal.