Lifecycle Modes & Legacy Apps

One call picks the runtime: App::mode()

Everything about how a request is handled — whether $_GET/$_SESSION are real, whether requests run concurrently, whether each .php file gets its own process — is decided by a single call near the top of app.php. You can pass the App::MODE_* constants (preferred) or their string equivalents. The trade-off behind every mode is the same one you met in Lesson 3: process-wide superglobals are not safe across concurrent coroutines. Each mode resolves that tension differently.

The first three are stable and well-trodden. mixed is the closest apples-to-apples PHP-FPM replacement; legacy-cgi is the conservative choice for apps that assume “this script runs alone.” The fourth, coroutine-legacy, is the ambitious one — and the rest of this lesson is an honest look at it.

The Superpower: Side-by-Side

The whole point of coroutine-legacy is that you get to write classic PHP syntax while keeping the performance and concurrency of coroutines. Let's look at what that means in practice:

// In pure Coroutine Mode, you must use $g
$g = \ZealPHP\RequestContext::instance();

$id = $g->get['id'] ?? null;

if (!isset($g->session['user'])) {
    $g->session['user'] = 'guest';
}

echo "Hello, " . $g->session['user'];

// In Coroutine-Legacy Mode, classic PHP just works!
session_start();

$id = $_GET['id'] ?? null;

if (!isset($_SESSION['user'])) {
    $_SESSION['user'] = 'guest';
}

echo "Hello, " . $_SESSION['user'];

In Coroutine-Legacy mode, ext-zealphp isolates $_GET, $_SESSION, and other global state per-coroutine. You don't have to rewrite your app to use RequestContext.

What coroutine-legacy is trying to do

It is a compatibility runtime: it lets traditional request-style PHP — the PHP-FPM “fresh state per request” mental model — run under OpenSwoole coroutine concurrency, with every request-state primitive isolated per coroutine. Real $_GET, $_POST, $_SESSION, $GLOBALS, function-local static $x, and require_once state all behave as if each request had its own process — while dozens of requests run concurrently on one worker.

It pulls this off with ext-zealphp, a small C extension that hooks OpenSwoole’s scheduler and snapshots/restores per-coroutine state across every yield. App::mode(App::MODE_COROUTINE_LEGACY) auto-enables the whole isolation stack:

use ZealPHP\App;

// Requires ext-zealphp: pie install zealphp/ext
App::mode(App::MODE_COROUTINE_LEGACY);
// equivalent to: superglobals(true) + isolation(coroutine) + silentRedeclare(true)
//                + includeIsolation(true) + coroutineGlobalsIsolation(true)
//                + coroutineStaticsIsolation(true)

$app = App::init('0.0.0.0', 8080);
$app->run();

The dividing line: how is your app’s class graph loaded?

The single best predictor of whether coroutine-legacy will be smooth is how your app loads its classes — because that determines whether the class graph can be warmed before concurrency arrives.