Coroutines

OpenSwoole coroutines are cooperative — they yield only on I/O, making parallel fetch trivial. ZealPHP enables HOOK_ALL so most PHP I/O (file, curl, sleep) becomes coroutine-aware automatically.

$app->route('/demo/coroutine/parallel', function() {
    $ch    = new Channel(3);
    $start = microtime(true);

    go(fn() => [$ch->push(simulated_fetch('users',  1))]);
    go(fn() => [$ch->push(simulated_fetch('orders', 1))]);
    go(fn() => [$ch->push(simulated_fetch('stats',  1))]);

    $results = [];
    for ($i = 0; $i < 3; $i++) $results[] = $ch->pop();

    return ['results' => $results, 'elapsed_s' => round(microtime(true) - $start, 3)];
    // All 3 run in parallel → ~1s total, not 3s
});

$app->route('/demo/coroutine/channel', function() {
    $ch = new Channel(1); // buffer of 1

    go(function() use ($ch) {
        co::sleep(1);
        $ch->push(['value' => 42, 'from' => 'producer coroutine']);
    });

    $result = $ch->pop(); // blocks until producer pushes
    return ['received' => $result, 'pattern' => 'producer/consumer'];
});

How it works

$g vs $_* — request state in both modes

The two forms diverge on one axis: how the framework populates them per request.

Why $g is the recommended convention: $g->get works in every mode with zero overhead — no extension required. With ext-zealphp, $_GET also works in both modes (per-coroutine safe). Either form is valid; $g->get is recommended because it works universally regardless of whether ext-zealphp is installed.

use ZealPHP\RequestContext;

$app->route('/article/{id}', function ($id) {
    $g = RequestContext::instance();

    // Recommended — always works in both modes:
    $g->get['id'] = $id;
    $g->server['PHP_SELF'] = '/article.php';

    // Also works with ext-zealphp (per-coroutine safe in both modes):
    //     $_GET['id'] = $id;
    //     $_SERVER['PHP_SELF'] = '/article.php';

    return App::include('/article.php');
});

Pages that touch request state link here rather than restating this rule: Legacy Apps (the Apache rewrite recipes), Sessions, Routing, and the API layer.

Lifecycle modes — pick a preset, or tune the two axes

The runtime is described by two orthogonal axes, with a one-call preset on top:

• App::superglobals(bool) — real process-wide $_GET/$_POST/$_SESSION populated per request (true) vs per-coroutine $g only (false).
• App::isolation(Isolation) — how a request is isolated. One value folds the old processIsolation × enableCoroutine × hookAll × cgiMode cross-product: Isolation::Coroutine (in-process, per-coroutine, concurrent), Isolation::CgiPool (warm pre-spawned PHP worker pool, interpreter resident, ~1-3 ms — the default for superglobals(true)), Isolation::CgiProc (proc_open subprocess per request, ~30-50 ms cold start — recursion-safe fallback for fresh-process semantics without a pre-spawned pool), Isolation::CgiFcgi (forward to an external FPM/upstream), or Isolation::None (in-process, sequential).

App::mode(string) sets both axes in one call. This is the recommended entry point — reach for the individual setters only to fine-tune:

Each axis decomposes into individually-exposed knobs (since v0.2.23). They default to null and resolve to "follow App::$superglobals" at App::run() time, so apps that only call App::mode() (or nothing) see no surprises:

Supported mode matrix

The isolation column is the resolved App::isolation() value; the knob columns it expands to (processIsolation / enableCoroutine / hookAll) are listed in the fine-grained table above.

Mode 6 — Coroutine + Process Isolation (the hybrid)

With ext-zealphp, both combos are safe (superglobals are saved/restored per coroutine). Without it, they’re gated on superglobals(true). With superglobals(false) the parent uses per-coroutine $g, so neither race exists either way — which means you can also combine coroutine concurrency at the parent with per-request subprocess isolation:

App::superglobals(false);     // per-coroutine $g (safe — no race)
App::processIsolation(true);  // public/*.php → CGI pool subprocess
App::enableCoroutine(true);   // parent runs coroutines (resolved from null)
App::hookAll(\OpenSwoole\Runtime::HOOK_ALL); // hooks pipe I/O (resolved from null)
// cgiMode('pool') is the default since v0.2.41 — warm FPM-style worker pool

What you get:

• Parent worker: N concurrent coroutines in flight, each with its own $g context. Routes, API, middleware run at full coroutine speed.
• App::include('/wp-login.php'): the parent pops a pool worker from its Coroutine\Channel, writes the request frame over stdin, and yields on the pipe read (HOOK_ALL hooks it). The scheduler runs other coroutines while the subprocess executes.
• Multiple coroutines dispatch in parallel: each coroutine pops a different pool worker (channel queue), up to cgiPoolSize (default 4). True request-level concurrency through the CGI path.
• Inside the subprocess: real $_GET / $_POST / $_SERVER / $_COOKIE / $_REQUEST populated per request, reset to clean state between requests. Full global-scope isolation per request — define() calls in a WordPress plugin don't leak across requests.

What you do NOT get (honest caveat):

• Coroutines do not run INSIDE the pool subprocess — each subprocess handles one request at a time, sequentially. To scale CGI concurrency, raise cgiPoolSize(), not enable a scheduler inside the subprocess (that would re-introduce the superglobals-race bug at a different layer).
• This is not the default. You must explicitly set App::processIsolation(true) — otherwise processIsolation resolves from null to follow sg=false → pi=false (no isolation). The defaults assume you either want full coroutine speed (no isolation) OR full superglobal compat (Legacy CGI mode); the hybrid is for the modern-mostly-with-legacy-pockets case.

Pinned by 13 lifecycle tests + 12 cgiPool tests at tests/Unit/LifecycleModesMatrixTest.php and tests/Unit/CGI/CgiPoolDispatchTest.php. See also "What cgiMode('pool') buys you" on the legacy-apps page for measured pool overhead.

The default coupling — null everywhere — preserves the historical behaviour for any app that doesn't touch these knobs. The zealphp-symfony bridge uses superglobals(true) + processIsolation(false) + sessionLifecycle(false) to get the Mixed-mode lifecycle.

What survives a request

Long-running PHP changes the rules from PHP-FPM. This is the discipline contract you accept when running on ZealPHP — what the framework isolates for you, and what you have to keep clean yourself.

Isolated per coroutine — framework handles this

In coroutine mode (App::superglobals(false), scaffold default since v0.2.4), RequestContext::instance() returns an instance stored on Coroutine::getContext($cid). It's allocated when the coroutine starts and freed when it ends. Every field on it is per-request:

NOT isolated — lives in worker process memory until the worker recycles

The following survive every coroutine boundary and every request boundary. The framework cannot isolate them. Treat them as worker-lifetime state.

The discipline contract

ZealPHP's per-request isolation is a discipline contract, not a runtime guarantee. The framework isolates what it owns (everything in RequestContext); it can't isolate what your code puts in static $foo or private static $instance. That state lives in worker process memory and survives every coroutine boundary, until the worker recycles.

This is the same trade-off every long-running PHP runtime makes. Hyperf and RoadRunner both ship worker recycling for exactly this reason — the surface area of state outside the framework's request-scoped object is too large to audit programmatically. The trust story is isolation + recycling, not either alone.

The backstop — worker recycling (max_request)

ZealPHP defaults to max_request=100000 since v0.2.4. After a worker handles 100,000 requests, OpenSwoole sends it SIGTERM, drains the current request, and the manager process forks a fresh worker. All process state — static variables, accumulated closures, leaked memory, the lot — is reset to zero. The TCP listener stays open via the manager, so no requests are dropped during the handoff.

Tuning knobs:

Safety matrix (per mode)

With ext-zealphp, both modes support coroutines — the distinction is about how request state is stored, not whether coroutines are available. superglobals(false) uses per-coroutine RequestContext; superglobals(true) uses PHP superglobals with ext-zealphp saving/restoring them per coroutine. Without ext-zealphp, superglobals(true) runs sequentially (one request at a time per worker) in the legacy/mixed shapes; explicitly combining superglobals(true) with enableCoroutine(true) (or a non-zero hookAll) throws a RuntimeException at boot rather than silently degrading — install ext-zealphp to run that combination (it is coroutine-legacy mode). Implicit file routes in processIsolation(true) mode run through the CGI bridge for true global-scope isolation. See the rendering methods and the universal return contract.

Common patterns