3.1 Upgrade Guide

• Version 3.1 mainly changes the minimum version of PHP to 8.1 and the minimum version of Swoole to 5.0.
• Introduced Pest testing framework
• Added hyperf/helper, migrated None namespace helper functions from Hyperf\Utils to hyperf/helper.
• Change the way hyperf/config loads multi-level configuration files to support . syntax, e.g., config('a.c')

Utils package changes

The helper functions in the original utils package did not have namespaces added, and might conflict with functions in other composer packages, so they were removed and replaced in 3.1.

There are two ways to handle this

• If no other packages are introduced into the application, it will cause function conflicts, so you can install hyperf/helper directly, and the helper package provides helper functions without namespaces, which is the same as the original utils package.
• Namespaces are introduced where helper functions are called, and can be refactored using rector refactoring docs here 🔎

Configuration file loading changes

In 3.0, configurations existed with config file name as the key, whereas in 3.1, hyperf/config multi-tier config files are loaded with relative directory.Config file name as the key.

Support for . syntax, such as config('a.c').

In this regard, it is important to note that the following two cases are handled in the original project

• 3.0 project has created a subdirectory in config/autoload, e.g. config/autoload/sub/a.php, the original config('a') needs to be changed to config('sub.a').
• Configuration file names in 3.0 projects contain . , such as config/autoload/a.b.php, will return the following structure when using config('a'), and if you also have a config/autoload/a.php configuration file, you will also get the result after merging the configuration items.

return [
    'a.php config key' => 'a.php config value',
    'b' => [
        'a.b.php config key' => 'a.b.php config value',
    ]
];

Other changes

1. the hyperf/metirc component no longer installs the prometheus dependency by default, so developers who need to use the prometheus engine need to execute the following command to load the dependencies:

composer require promphp/prometheus_client_php

2. Changes to withHeaders for Request and Response

before v3.1 will save the original data, similar to array_merge. After version v3.1, all headers will be directly replaced.

<?php
// before v3.1 
$request->withHeader('foo', 1)->withHeader('bar', 2); // ['foo' => [1], 'bar' => [2]]
$request->withHeader('foo', 1)->withHeader('foo', 2); // ['foo' => [2]]
$request->withAddedHeader('foo', 1)->withAddedHeader('foo', 2); // ['foo' => [1, 2]]

$request->withHeaders(['foo' => 1])->withHeaders(['bar' => 2]); // ['foo' => [1], 'bar' => [2]]

// after v3.1
$request->withHeader('foo', 1)->withHeader('bar', 2); // ['foo' => [1], 'bar' => [2]]
$request->withHeader('foo', 1)->withHeader('foo', 2); // ['foo' => [2]]
$request->withAddedHeader('foo', 1)->withAddedHeader('foo', 2); // ['foo' => [1, 2]]

$request->withHeaders(['foo' => 1])->withHeaders(['bar' => 2]); // ['bar' => [2]]

$request->setHeader('foo', 1)->setHeader('bar', 2); // ['foo' => [1], 'bar' => [2]]
$request->setHeader('foo', 1)->setHeader('foo', 2); // ['foo' => [2]]
$request->addHeader('foo', 1)->addHeader('foo', 2); // ['foo' => [1, 2]]

$request->setHeaders(['foo' => 1])->setHeaders(['bar' => 2]); // ['bar' => [2]]

3. AMQP consumer consumeMessage method return value is adjusted to Result enum

<?php
// before v3.1
public function consumeMessage($data, AMQPMessage $message): string
{
    return Result::ACK;
}
// after v3.1
public function consumeMessage($data, AMQPMessage $message): Result
{
    return Result::ACK;
}