Hyperf: a coroutine-oriented PHP framework

It relies only on the official Hyperf repository page supplied for this guide. Where that page is silent, the guide says the answer is unknown.

What Hyperf is

Hyperf is a PHP framework. Its README describes it as a PHP CLI framework powered by a coroutine server and a large set of components, aimed at microservices and middleware. It is licensed under MIT according to the repository.

Be precise about classification. Hyperf is not PHP core and not a standalone PHP runtime, and it is not a CMS product like Drupal. It runs on PHP and depends on a coroutine extension, which the README names as Swoole or Swow. The README also states that its core components follow PSR standards and can be used in other frameworks. That is a project claim, not something verified here.

Architecture

The README says the architecture combines coroutines, dependency injection, events, annotations and AOP (aspect-oriented programming). Its dependency injector is described as AOP-enabling, so classes can be made pluggable and meta-programmable.

The README also lists coroutine-compatible clients and servers: MySQL, Redis, WebSocket, JSON RPC, gRPC, Guzzle HTTP, Elasticsearch, Consul, ETCD, AMQP, connection pooling, a circuit breaker and more. Its stated rationale is that developers should not need to write coroutine-compatible versions of these libraries themselves. Familiar framework pieces such as middleware, an event manager, an ORM, validation, translation and several view engines are also listed.

The repository mentions related projects: Nano (a zero-config, no-skeleton distribution that lets you build an app from a single PHP file), GoTask, Jet (an RPC client) and Box (tooling for PHP environments, packaging and a reverse proxy). Their maturity, versions and support status are unknown from this source.

Execution model

In classic PHP-FPM style, each request normally starts with fresh PHP state, runs, and is torn down. Hyperf is a CLI application. It starts a long-lived server process, and requests are handled inside that process by coroutines.

Swoole and Swow are the named extensions. The source does not mention Open Swoole, a separate project from Swoole. Whether Hyperf works with it is unknown here. Do not assume that the two are interchangeable.

State leakage and cleanup in persistent workers

With persistent workers, memory outlives a single request. That brings several risks:

• Static properties and globals keep their values after a request ends.
• Services held in a dependency injection container may be shared across requests, so storing per-request data such as the current user or a tenant on them is risky.
• Coroutines interleave inside one worker, so a shared mutable property can be overwritten by another in-flight request.
• Open connections, file handles, caches and growing arrays can accumulate.

Safer habits follow from this:

1. Treat services as stateless. Pass request data through parameters or a request-scoped context.
2. Use the framework's documented coroutine-context facilities for per-request values. Check the official documentation for the exact facility, because this guide does not invent API names.
3. Reset or release anything you set, preferably in a finally block, so it happens even when an exception is thrown.
4. Return pooled connections and close handles you opened.
5. Review static caches for unbounded growth.

The second example below demonstrates the leakage pattern with plain PHP. It does not use Hyperf, and it only simulates a persistent worker.

Practical use cases

The README positions Hyperf for web servers, gateway servers, distributed middleware, microservices, game servers and IoT. It suits teams that want a long-running PHP service with built-in clients for RPC, queues and service discovery, and that are comfortable operating a persistent process. A classic form-handling site on shared hosting is a poor fit, since a CLI coroutine server cannot run in such an environment.

Installation approach

The supplied source gives requirements but no install commands, so none are invented here. The README lists:

• Linux, OS X, Cygwin, WSL or Windows
• PHP 8.1 or newer
• Swoole 5.0 or newer, or Swow 1.4 or newer

PHP 8.4 support is not confirmed by this source, and neither is PHP 8.5. The learning track targets PHP 8.4 with 8.5 planned, so verify compatibility in the official documentation and release notes before building on it. The first example is a preflight script that checks your PHP version and loaded extensions. For project creation, follow the official documentation linked from the README. That may involve Composer and a skeleton or Nano, but the exact steps are unknown here.

Strengths

• Coroutine-based concurrency with many coroutine-aware components included.
• Strong dependency injection with AOP, annotations and attributes.
• PSR-oriented design (PSR-7, PSR-14 and PSR-15 appear in the repository topics).
• Permissive MIT license.
• An active-looking repository with many commits, changelogs and documentation in more than one language.

The README includes a self-reported benchmark on specific hardware and says Hyperf beats PHP-FPM frameworks. This guide neither reproduces nor endorses those figures. Measure your own workload.

Limitations

• It needs a coroutine extension (Swoole or Swow), which classic shared hosting usually lacks.
• Persistent workers introduce state leakage risks that request-per-process PHP largely hides.
• Not every PHP library is coroutine-safe. Blocking calls can stall a worker, and the source does not list which libraries are safe.
• Current version, long-term support policy and deprecations are unknown from the supplied source, so lifecycle is marked unknown.

Deployment

The source gives no deployment recipe, so details such as process supervision, container images and reverse proxy configuration are unknown here. General cautions apply. The README's benchmark uses a local address on port 9501, so bind any development server to 127.0.0.1 and put a reverse proxy in front of any production service. Plan graceful restarts, since long-lived workers hold code and memory. The README mentions Box as offering reverse proxy and deployment management, but evaluate it separately. They are not browser exercises.

Examples in this guide

Example one checks the environment against the README's stated requirements. Example two simulates persistent-worker state leakage and cleanup in plain PHP.

Source

The official repository is listed in the links section. Read its README and the documentation it references before starting a real project.

<?php

declare(strict_types=1);

// Checks the requirements stated in the Hyperf README:
// PHP 8.1+ and Swoole 5.0+ or Swow 1.4+.
// This does not prove PHP 8.4 compatibility; consult official docs.

$ok = true;

echo 'PHP version: ' . PHP_VERSION . PHP_EOL;
if (PHP_VERSION_ID < 80100) {
    echo 'FAIL: PHP 8.1 or newer is required.' . PHP_EOL;
    $ok = false;
}

$coroutineFound = false;

if (extension_loaded('swoole')) {
    $version = (string) phpversion('swoole');
    echo 'swoole extension: ' . $version . PHP_EOL;
    if (version_compare($version, '5.0.0', '>=')) {
        $coroutineFound = true;
    } else {
        echo 'WARN: Swoole 5.0+ is listed in the README.' . PHP_EOL;
    }
} else {
    echo 'swoole extension: not loaded' . PHP_EOL;
}

if (extension_loaded('swow')) {
    $version = (string) phpversion('swow');
    echo 'swow extension: ' . $version . PHP_EOL;
    if (version_compare($version, '1.4.0', '>=')) {
        $coroutineFound = true;
    } else {
        echo 'WARN: Swow 1.4+ is listed in the README.' . PHP_EOL;
    }
} else {
    echo 'swow extension: not loaded' . PHP_EOL;
}

if (!$coroutineFound) {
    echo 'FAIL: no suitable Swoole or Swow extension detected.' . PHP_EOL;
    $ok = false;
}

echo $ok ? 'Result: requirements look satisfied.' . PHP_EOL : 'Result: requirements not met.' . PHP_EOL;
exit($ok ? 0 : 1);

php --version
php check-env.php

<?php

declare(strict_types=1);

// Simulates a persistent worker: this process stays alive across "requests".
// Plain PHP only; it does not use Hyperf, Swoole or Swow.

final class LeakyUserHolder
{
    public static ?string $currentUser = null;
}

final class RequestState
{
    /** @var array<string, string> */
    private static array $data = [];

    public static function set(string $key, string $value): void
    {
        self::$data[$key] = $value;
    }

    public static function get(string $key): ?string
    {
        return self::$data[$key] ?? null;
    }

    public static function reset(): void
    {
        self::$data = [];
    }
}

function handleLeaky(?string $user): string
{
    if ($user !== null) {
        LeakyUserHolder::$currentUser = $user;
    }

    return LeakyUserHolder::$currentUser ?? 'anonymous';
}

function handleSafe(?string $user): string
{
    try {
        if ($user !== null) {
            RequestState::set('user', $user);
        }

        return RequestState::get('user') ?? 'anonymous';
    } finally {
        RequestState::reset();
    }
}

$requests = ['alice', null, 'bob', null];

echo 'Leaky handler:' . PHP_EOL;
foreach ($requests as $i => $user) {
    echo sprintf('  request %d sees user: %s', $i + 1, handleLeaky($user)) . PHP_EOL;
}

echo 'Handler with cleanup:' . PHP_EOL;
foreach ($requests as $i => $user) {
    echo sprintf('  request %d sees user: %s', $i + 1, handleSafe($user)) . PHP_EOL;
}

php --version
php leak-demo.php