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. 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.

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('coroutine-legacy') auto-enables the whole isolation stack:

use ZealPHP\App;

// Requires ext-zealphp: pie install sibidharan/ext-zealphp
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.