1.1 升級指南

1.1 版新增了很多的功能，但一些改動也涉及到了對 Skeleton 骨架的調整，以及配置項的結構調整，如果您已經投入了業務使用的專案且是基於官方提供的 Skeleton 專案建立的 1.0 應用專案，那麼可以根據下面的內容點來調整您的骨架專案，如果您是一個新的專案，按照文件通過 composer create-project hyperf/hyperf-skeleton 命令建立新的專案即可使用新的 skeleton 結構。

升級 Swoole 到 4.4+

1.1 版將最低的 Swoole 版本要求從 4.3+ 提升到了 4.4+，這兩個版本之間有一些使用上的細節問題，Hyperf 已經在較早的版本便已適配了，對於 Hyperf 的使用者而言無需理會這之間的差異，我們提升最低 Swoole 版本要求主要是為了減少我們的歷史負擔，而 Swoole 4.4 作為 Swoole 的 LTS(長期支援版本) 也意味著更加的穩定可靠。

Hyperf 在啟動時會進行 Swoole 版本檢測，但為了更好的統一各處對 Swoole 版本的依賴約束，我們建議您將 composer.json 內對 Swoole 的依賴條件改為 "ext-swoole": ">=4.4"。

增加 SWOOLE_HOOK_FLAGS 常量

在應用的入口檔案 bin/hyperf.php 以及單測的入口檔案 test/bootstrap.php 裡增加一行常量定義如下：

! defined('SWOOLE_HOOK_FLAGS') && define('SWOOLE_HOOK_FLAGS', SWOOLE_HOOK_ALL);

參考：入口檔案參考單測入口檔案參考

移動 config/dependencies.php 檔案並調整檔案結構

移動 config/dependencies.php → config/autoload/dependencies.php，並去除配置檔案中的第一層 dependencies，如下：

1.0 的檔案結構：

<?php
// config/dependencies.php 檔案

return [
    'dependencies' => [
        FooInterface::class => Foo::class
    ],
];

1.1 的檔案結構：

<?php
// config/autoload/dependencies.php 檔案

return [
    FooInterface::class => Foo::class
];

調整 config/container.php 檔案的內容

由於 1.1 版本調整了 dependencies.php 檔案的位置和結構，所處我們還需要調整一下 config/container.php 檔案，以便依賴注入容器能夠正確的執行，與此同時，我們也為 config/container.php 提供了更加簡便的寫法，DefinitionSourceFactory 將很多預設的行為聚合了起來，您只需將 config/container.php 檔案的內容更換成下面的內容即可：

預設開啟註解掃描快取功能，可修改 DefinitionSourceFactory 入參的第一個引數來關閉此功能

<?php
/**
 * Initial a dependency injection container that implemented PSR-11 and return the container.
 */
declare(strict_types=1);

use Hyperf\Di\Container;
use Hyperf\Di\Definition\DefinitionSourceFactory;
use Hyperf\Utils\ApplicationContext;
use Psr\Container\ContainerInterface;

$container = new Container((new DefinitionSourceFactory(true))());
if (! $container instanceof ContainerInterface) {
    throw new RuntimeException('The dependency injection container is invalid.');
}
return ApplicationContext::setContainer($container);

調整 WebSocket 控制器

由於 1.1 版本調整了 onMessage 和 onOpen 的入參約束，所以需要手動修改其為 Swoole\WebSocket\Server，具體程式碼如下

<?php
declare(strict_types=1);

namespace App\Controller;

use Hyperf\Contract\OnMessageInterface;
use Hyperf\Contract\OnOpenInterface;
use Swoole\Http\Request;
use Swoole\Websocket\Frame;
use Swoole\WebSocket\Server as WebSocketServer;

class WebSocketController implements OnMessageInterface, OnOpenInterface
{
    public function onMessage(WebSocketServer $server, Frame $frame): void
    {
    }

    public function onOpen(WebSocketServer $server, Request $request): void
    {
    }
}

調整自定義元件的 ConfigProvider

1.0 版本中 scan.path 在 1.1 版本中調整為 annotations.scan.path，您需要修改所有自定義元件的 ConfigProvider 類來適配此變更，如您的自定義元件不涉及到註解掃描的功能配置，則可忽略此調整，如下所示：

1.0 的 ConfigProvider 檔案結構：

class ConfigProvider
{

    public function __invoke(): array
    {
        return [
            'scan' => [
                'paths' => [
                    __DIR__,
                ],
            ],
        ];
    }
}

1.1 的 ConfigProvider 檔案結構：

class ConfigProvider
{

    public function __invoke(): array
    {
        return [
            'annotations' => [
                'scan' => [
                    'paths' => [
                        __DIR__,
                    ],
                ],
            ],
        ];
    }
}

調整預設的本地化語言

如果您在之前有使用 hyperf/translation 元件，那麼您需要檢查一下 config/autoload/translation.php 檔案內的 locale 配置項，如為 zh-CN，則需要改為 zh_CN，在 1.1 版本，我們統一了這個配置的值。

調整 composer.json 的依賴

由於要升級到 1.1 版本的元件，而原來 skeleton 專案預設情況下是依賴 1.0.x 版本的元件的，所以我們需要對依賴的約束條件進行一些調整，將原來所有 Hyperf 元件的依賴 ~1.0.0 修改為 ~1.1.0，修改完後需執行 composer update 來將依賴項升級到 1.1 版本。

必須將所有 Hyperf 依賴都升級到 1.1 版本才可用，因為 1.1 調整了元件適配的 ConfigProvider 機制。

完成升級

至此，1.1 升級即已完成，但由於 Hyperf 的各個底層檔案都是可以通過 DI 來實現重寫的，如您重寫了某些本次升級調整到了的框架內部檔案，您仍需再根據您的實際情況進行一定的調整。

如您在升級上或升級後遇到任何的問題，請前往 Github Issue 提交您的 issue，說明您遇到的問題，我們會盡快幫助您解決。

6.1 KiB Raw Blame History Unescape Escape