Running Legacy PHP Apps

WordPress compatibility showcase: front page, login, posts, and REST API working (the WP-admin dashboard has documented limits under coroutine concurrency) through the ZealPHP CGI worker bridge in compatibility mode — with documented limits. The bridge exists so traditional PHP code that assumes a fresh process per request (WordPress, Drupal, define()-heavy plugins) can run on OpenSwoole's long-lived workers via a warm, pre-spawned PHP worker pool (App::cgiMode('pool')) — the same FPM-style model, with the interpreter resident in memory between requests. The same app.php works for Drupal, Laravel-on-FPM-shape, and other traditional PHP applications.

WordPress front page

Admin dashboard — full menu, widgets, Quick Draft

Posts management — CRUD, bulk actions, filters

50-app compatibility sweep — May 2026

We ran a structured compatibility sweep against 50 popular PHP applications on Docker lab (PHP 8.4.21 + OpenSwoole 26.2 + ext-zealphp 0.3.25), testing each across all four production modes. Full results in docs/compatibility-database.md.

Apps that PASS in ALL 4 modes (no modifications needed)

Five apps were tested 5× per mode (20 requests total, sequential + concurrent) and passed every request:

• Kanboard — project management — zealphp-kanboard
• Joomla — major CMS (Symfony-based) — zealphp-joomla
• Roundcube — webmail — zealphp-roundcube
• OpenCart — e-commerce — zealphp-opencart
• Adminer (with functionIsolation(true)) — DB admin — zealphp-adminer

App-by-app summary (Mode 1 = CGI Pool, Mode 3 = Sync + functionIsolation)

* with App::functionIsolation(true) — ext-zealphp 0.3.5+ feature that snapshots CG(function_table) + CG(class_table) at worker boot and cleans request-scoped additions at request end. Auto-skipped when the app registers its own Composer autoloader from documentRoot.

The two breakthroughs the sweep drove

• App::functionIsolation(true) — fixes the classic "Cannot redeclare function" crash that breaks single-file legacy PHP apps (Adminer, TinyFileManager, FreshRSS) on long-running servers. Each request gets fresh function/class state via ext-zealphp's C-level cleanup. ~3ms overhead.
• CGI Pool chdir() fix — Apache mod_php sets the working directory to the script's directory before each include. ZealPHP's pool worker now does the same. Fixes Cacti, OpenCart, and other apps using relative includes (require './include/auth.php').

Known limitations — things ZealPHP won't do

Before going deep, do the 30-second dealbreaker scan. If your app depends on any of the categories marked ❌ below and you can't put a front proxy in front of ZealPHP, this isn't the right runtime. If you pass this gate, the porting story is clean — keep reading.

Apache-side features not supported

nginx-side features not supported (or partial)

ZealPHP internal limitations

Headline: the dealbreakers list is short and the items on it are either (a) dead tech nobody uses anymore (SSI, imagemaps, CERN meta files), (b) protocol-scope mismatches that belong to dedicated servers (WebDAV, SMTP, L4 proxy), or (c) features intentionally delegated to a front proxy (multi-host TLS, load balancing, HTTP/3, reverse proxy). For the ~95% of PHP apps that don't depend on these, the migration is clean.

Migration ergonomics — one-liner Apache parity

Earlier ZealPHP releases needed a 5-line boot preamble to set $_SERVER globals before serving a legacy file. App::include() owns that preamble now: leading slash optional, Apache-document-root convention (paths are relative to public/), and the framework auto-populates $_SERVER['PHP_SELF'] / SCRIPT_NAME / SCRIPT_FILENAME exactly as Apache's mod_php does.

$app->setFallback(function () {
    $g = RequestContext::instance();
    $g->server['PHP_SELF']        = '/index.php';
    $g->server['SCRIPT_NAME']     = '/index.php';
    $g->server['SCRIPT_FILENAME'] =
        App::$cwd . '/public/index.php';
    App::includeFile(
        App::$cwd . '/public/index.php'
    );
});

$app->setFallback(fn() => App::include('/index.php'));

// Paths are relative to public/ (Apache DocumentRoot
// convention) — leading slash optional. The framework
// auto-populates $_SERVER preamble, blocks traversal
// outside public/, and honours the universal return
// contract — see /responses#return-contract.

How It Works

Three framework features enable legacy app compatibility:

<?php
require 'vendor/autoload.php';
use ZealPHP\App;

// One-call preset: superglobals(true) + isolation(CgiPool) + cgiMode('pool')
// Use this for unmodified WordPress/Drupal and other require_once-bootstrap apps.
App::mode(App::MODE_LEGACY_CGI);
App::$ignore_php_ext = false;

$app = App::init('0.0.0.0', 8080);
$app->run(['task_worker_num' => 0]);
// PHP files in public/ are served automatically via the warm CGI pool

WordPress — tested end-to-end

The companion repo sibidharan/zealphp-wordpress ships an unmodified WordPress 6.7.1 install bound to ZealPHP via a ~30-line app.php (full WP frontend, wp-admin, REST API, plugin system, htaccess-equivalent rewrites). Tested live against this branch in Chrome:

One-line WP config — drop this in your app.php and unmodified WordPress works:

<?php
require 'vendor/autoload.php';
use ZealPHP\App;

App::mode(App::MODE_LEGACY_CGI);          // mod_php-style superglobals + warm FPM-style worker pool
App::cgiPoolMaxRequests(1);               // recycle each request — WP needs a fresh boot
// App::cgiSubprocessAutoload(false);     // default — DO NOT enable for WP
App::$ignore_php_ext = false;             // allow /wp-login.php in URLs

$app = App::init('0.0.0.0', 9501);

$app->setFallback(function() {            // WP front controller
    App::include('/index.php');
});

$app->run(['task_worker_num' => 0]);

Pool mode for WordPress — set cgiPoolMaxRequests(1)

WordPress needs a fresh interpreter per request because its require_once bootstrap chain can't be re-run inside an already-warm worker. Pair the default pool with App::cgiPoolMaxRequests(1) to get exactly that: every pool subprocess exits after one request and the parent respawns it from the pre-spawned queue — fresh-process semantics, but the parent always has a warm worker ready to receive the next request (so you keep the pool's bounded first-request latency):

<?php
require 'vendor/autoload.php';
use ZealPHP\App;

App::mode(App::MODE_LEGACY_CGI);
App::cgiPoolSize(8);                      // 8 subprocesses pre-spawned per HTTP worker
App::cgiPoolMaxRequests(1);               // recycle after EVERY request — WP needs fresh boot
App::$ignore_php_ext = false;

$app = App::init('0.0.0.0', 9501);
$app->setFallback(function() { App::include('/index.php'); });
$app->run();

Experimental: Concurrent WordPress via App::MODE_COROUTINE_LEGACY

If you want to run WordPress concurrently using coroutines instead of a worker pool, you can use the experimental App::MODE_COROUTINE_LEGACY mode. This requires ext-zealphp to isolate superglobals, statics, and require_once state per coroutine natively.

<?php
require 'vendor/autoload.php';
use ZealPHP\App;

// Requires ext-zealphp to be installed and loaded!
App::mode(App::MODE_COROUTINE_LEGACY);
App::$ignore_php_ext = false;

$app = App::init('0.0.0.0', 9501);
$app->setFallback(function() { App::include('/index.php'); });
$app->run();

The framework's pool_worker.php already does FPM-style $GLOBALS snapshot/restore between requests — clears $wp_did_header, $wpdb, $wp_query, etc. — but WordPress's require_once chain caches the bootstrap (wp-load.php → wp-settings.php → new WP() assignments) and PHP can't un-cache require_once entries in standard PHP. Recycling the subprocess every request bypasses this by getting a fresh interpreter where require_once is uncached.

Why cgiSubprocessAutoload(false) is the default

Issue #18 (the v0.2.41 WP autoload regression). Between v0.2.0 and v0.2.20, cgi_worker.php gained a require_once vendor/autoload.php at startup so apps that needed \ZealPHP\App inside the subprocess could use it (issue #17). That autoload load measures ~30 ms per worker spawn on a Ryzen 9 7900X.

For modern apps that don't make 10 ms-timeout self-calls, 30 ms is invisible. But WordPress's wp_cron() fires a non-blocking POST /wp-cron.php with timeout = 0.01. When a recycled pool worker (under cgiPoolMaxRequests(1)) takes longer to warm up than the wp-cron client's timeout window allows, the POST connection arrives at the parent OpenSwoole worker before any pool worker is free to accept it, accumulating as half-closed sockets. By the 2nd request, the pool is fully blocked.

The fix: gate the autoload on App::cgiSubprocessAutoload(true) — default off — keeping the pool worker's startup path lean. Apps that need ZealPHP classes inside CGI dispatch (rare — most legacy apps ship their own bootstrap) opt in. Pinned by tests/Unit/CgiSubprocessAutoloadTest.php (5 tests including a source-level canary against future regressions).

What cgiMode('pool') buys you — measured

cgiMode('pool') is the default since v0.2.41 — the FPM-style warm worker pool: a fixed set of PHP interpreters that stay resident in memory and are reused across requests. The numbers below are measured on this machine (Ryzen 9 7900X, OpenSwoole 26.2, PHP 8.3) so you can compare them directly to the bench results elsewhere in the docs.

Reading the numbers: the pool itself adds ~90 microseconds of dispatch overhead per request (p50 = 28 μs, p99 = 47 μs) — the cost of handing the request to an already-warm interpreter and reading its response back. That overhead vanishes inside any non-trivial PHP file — by the time WordPress's autoloader has run, the ~90 μs IPC cost is invisible. The whole point of the pool is that the PHP interpreter never leaves memory: there is no per-request interpreter spin-up, so legacy public/*.php dispatch lands within a small constant of the modern coroutine route.

Reproduce locally:

# Pool — warm FPM-style workers, IPC-only dispatch
php scripts/bench-fcgi-pool.php 1000 4 500

# Args: <requests> <pool-workers> <recycle-after-N-requests>
# Fixture is `echo "ok";` so you measure pool round-trip, not app code.

vs PHP-FPM: same semantic model (warm worker pool, recycled after N requests), so per-request cost is in the same ballpark as your FPM pool — minus the FastCGI socket hop and the separate web-server bridge, since ZealPHP's HTTP server is built in. /vs-fpm covers the apples-to-apples measurement story. The honest claim is "FPM-equivalent semantics + ZealPHP-managed (one less daemon to install, no HTTP↔FastCGI bridge)."

What you actually get from pool mode (beyond the bench numbers)

• True global-scope isolation per request. Each pool subprocess is a fresh exec'd PHP process (NOT a fork of the HTTP worker), so it doesn't inherit ZealPHP's autoloader, classes, or memory. define()-heavy plugins, classes that re-declare in plugin updates, function tables that grow per request — none of it leaks.
• FPM-style recycling. cgiPoolMaxRequests(N) (default 500) makes each pool worker exit cleanly after N requests; the parent respawns it. Defense against slow memory leaks in user PHP that would otherwise compound over millions of requests.
• Per-HTTP-worker private pools. No global IPC bottleneck — each OpenSwoole HTTP worker owns its own cgiPoolSize subprocesses with a Coroutine\Channel queue. Scales with worker count.
• Real $_GET / $_POST / $_SERVER / $_COOKIE inside the subprocess. Pinned by 5 unit tests in tests/Unit/CGI/CgiPoolDispatchTest.php (testPostSuperglobalReachesSubprocess, etc.).
• Auto-respawn on crash. proc_get_status polled before each dispatch; dead workers are replaced transparently.

The hybrid: parent runs coroutines, public/*.php gets isolation

The mode-table on the coroutines page documents this as Mode 6 — Coroutine + Process Isolation. It's the "best of both worlds" combo you can opt into when you want the modern app to be concurrent AND have occasional legacy isolated PHP:

<?php
require 'vendor/autoload.php';
use ZealPHP\App;

// Modern app — per-coroutine $g in the parent worker (no race)
App::superglobals(false);

// public/*.php → CGI pool subprocess (true global-scope isolation per request)
App::processIsolation(true);

// Parent runs coroutines. With HOOK_ALL, the pipe read inside cgiPool
// YIELDS while the subprocess executes — other coroutines run in parallel.
// Both default to null → resolve to !sg → these values. Explicit for clarity:
App::enableCoroutine(true);
App::hookAll(\OpenSwoole\Runtime::HOOK_ALL);

// cgiMode('pool') is the default since v0.2.41. Tune pool size to your needs:
App::cgiPoolSize(8);            // 8 isolated PHP subprocesses per HTTP worker
App::cgiPoolMaxRequests(1000);  // recycle after 1000 requests (FPM parity)

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

// Route handlers in route/*.php run at full coroutine speed.
// public/wp-login.php dispatches to the isolated pool.
// Parent yields on the pipe read → multiple coroutines dispatch in parallel.

With ext-zealphp (v0.3.0+), superglobals(true) + enableCoroutine(true) is now fully supported — the extension saves/restores $_GET/$_SESSION per coroutine on every yield/resume. Without ext-zealphp, the validator still refuses this combination. Mode 6 is pinned by tests/Unit/LifecycleModesMatrixTest.php#testMode6CoroutineIsolatedHybrid.

Dual-runtime — one codebase, Apache AND ZealPHP at once

The strongest migration story isn't "rewrite for ZealPHP." It's "run the same source tree on both servers simultaneously" — Apache+mod_php for the battle-tested path, ZealPHP for speed and coroutines — and cut over gradually with zero risk. This is exactly how Selfmade Ninja Labs migrated: one volume, two servers, same files (running on dev today, production cutover next).

The mechanism is a tiny compat shim that gives application code a single accessor — $g->get, $g->session, etc. — that resolves correctly in whichever runtime is loading the file:

<?php
// Include this ONCE at the top of every entry point — on BOTH servers.
if (!isset($GLOBALS['g'])) {
    if (class_exists('\ZealPHP\RequestContext', false)) {
        // ZealPHP is loaded → use the framework's per-request context.
        // Coroutine mode: per-coroutine, concurrency-safe. The ONLY safe
        // accessor there ($_GET/$_SESSION are intentionally empty).
        $GLOBALS['g'] = \ZealPHP\RequestContext::instance();
    } else {
        // Apache + mod_php → ZealPHP isn't here at all. Build $g from
        // references to PHP's real superglobals so $g->get IS $_GET.
        $GLOBALS['g'] = (object) [
            'get'     => &$_GET,    'post'    => &$_POST,
            'server'  => &$_SERVER, 'cookie'  => &$_COOKIE,
            'files'   => &$_FILES,  'request' => &$_REQUEST,
            'session' => &$_SESSION,
        ];
    }
}
$g = $GLOBALS['g'];

Then application code uses only $g->X — never $_GET/$_SESSION directly:

<?php
require_once __DIR__ . '/../vendor/zealphp/zealphp/compat/g.php';

session_start();
$g->session['hits'] = ($g->session['hits'] ?? 0) + 1;
$filter = $g->get['filter'] ?? 'all';
echo "Filter: {$filter}, hits: {$g->session['hits']}";

With ext-zealphp (v0.3.0+): App::mode(App::MODE_COROUTINE_LEGACY) is safe — $_GET/$_SESSION are per-coroutine. Legacy code using $_GET works unchanged with full coroutine concurrency. $g->X also works — both accessors are valid in all modes. Without ext-zealphp, coroutine-mode apps must use $g->X exclusively (superglobals stay empty to prevent races).

Apache rewrite recipes — the 12 patterns

Real .htaccess files are full of RewriteRule destinations that end in .php. Each recipe below shows the Apache directive and its ZealPHP equivalent. Every example uses the $g form for query-string injection — works in both modes, no per-coroutine leak in coroutine mode. The legacy $_GET equivalent appears as a comment for readers porting older code.

Recipe A — Strip .php extension (clean URLs)

# URL /about → public/about.php
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteCond %{REQUEST_FILENAME}\.php -f
RewriteRule ^(.+)$ $1.php [L]

// The implicit /{file} route already matches both
// /about and /about.php to public/about.php when
// $ignore_php_ext is true.
App::$ignore_php_ext = true;

Recipe B — Pretty URL → real .php file (with route param)

RewriteRule ^my-page$              /pages/my-page.php             [L]
RewriteRule ^article/([0-9]+)\.html$ /article.php?id=$1           [L,QSA]
RewriteRule ^user/([a-z0-9-]+)$    /user/profile.php?slug=$1      [L,QSA]

use ZealPHP\RequestContext;

$app->route('/my-page',
    fn() => App::include('/pages/my-page.php'));

$app->patternRoute('/article/([0-9]+)\.html', function ($id) {
    $g = RequestContext::instance();
    $g->get['id'] = $id;          // legacy: $_GET['id'] = $id
    return App::include('/article.php');
});

$app->patternRoute('/user/([a-z0-9-]+)', function ($slug) {
    $g = RequestContext::instance();
    $g->get['slug'] = $slug;      // legacy: $_GET['slug'] = $slug
    return App::include('/user/profile.php');
});

Recipe C — Front controller (WordPress / Drupal / Laravel)

# WordPress / Laravel — try real file, else hand to index.php
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule . /index.php [L]

# Drupal 7 / older CMSes — pass the path as ?q=
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^(.*)$ index.php?q=$1 [L,QSA]

use ZealPHP\RequestContext;

// WordPress / Laravel — fallback handler.
// Implicit router already tried public/{file}.php;
// setFallback() catches everything else.
$app->setFallback(fn() => App::include('/index.php'));

// Drupal — populate $g->get['q'] (legacy: $_GET['q']):
$app->setFallback(function () {
    $g = RequestContext::instance();
    $g->get['q'] = ltrim(parse_url(
        $g->server['REQUEST_URI'], PHP_URL_PATH
    ) ?? '', '/');
    return App::include('/index.php');
});

Recipe D — API prefix → single front controller

# /api/v1/users/42 → /api/index.php
# with REQUEST_URI preserved
RewriteRule ^api/(.*)$ /api/index.php [L,QSA]

use ZealPHP\RequestContext;

$app->nsPathRoute('api', '{path}', function (string $path) {
    $g = RequestContext::instance();
    $g->get['path'] = $path;       // legacy: $_GET['path'] = $path
    return App::include('/api/index.php');
});

Recipe E — Specific .php file in subdirectory

RewriteRule ^admin/?$         /admin/login.php       [L]
RewriteRule ^admin/users$     /admin/users/index.php [L]
RewriteRule ^checkout/done$   /shop/thankyou.php     [L]

$app->route('/admin',         fn() => App::include('/admin/login.php'));
$app->route('/admin/users',   fn() => App::include('/admin/users/index.php'));
$app->route('/checkout/done', fn() => App::include('/shop/thankyou.php'));

Recipe F — Block direct access to internal .php files

# WordPress: prevent direct hits on wp-includes/*.php
RewriteRule ^wp-includes/(.+\.php)$ - [F,L]

// Refuse with 403 (universal return contract — int = status).
$app->nsPathRoute('wp-includes', '{rest}(\.php)?', fn() => 403);

Recipe G — HTTPS canonical scheme

RewriteCond %{HTTPS} off
RewriteRule (.*) https://%{HTTP_HOST}%{REQUEST_URI} [R=301,L]

use Psr\Http\{Server\MiddlewareInterface,
              Message\ResponseInterface};
use OpenSwoole\Core\Psr\Response;

$app->addMiddleware(new class implements MiddlewareInterface {
    public function process($request, $handler): ResponseInterface {
        if (($request->getServerParams()['HTTPS'] ?? '') !== 'on') {
            $url = 'https://' . $request->getUri()->getHost()
                 . $request->getUri()->getPath();
            return (new Response(''))->withStatus(301)
                ->withHeader('Location', $url);
        }
        return $handler->handle($request);
    }
});

Recipe H — Canonical host (www vs apex)

RewriteCond %{HTTP_HOST} !^www\. [NC]
RewriteRule (.*) https://www.%{HTTP_HOST}%{REQUEST_URI} [R=301,L]

// Inspect Host header; if missing www., 301 to the www form.
// See Recipe G for the full middleware skeleton.

Recipe I — Maintenance mode

RewriteCond %{REMOTE_ADDR} !^203\.0\.113\.42$
RewriteRule .* /maintenance.html [R=503,L]

// Check $g->server['REMOTE_ADDR']; non-allow-listed IPs get
// a 503 response served via App::include('/maintenance.php').
// Universal return contract handles status + body.

Recipe J — Custom error pages (Apache ErrorDocument)

ErrorDocument 404 /custom-404.php
ErrorDocument 500 /custom-500.php

$app->setErrorHandler(404, fn() => App::include('/custom-404.php'));

$app->setErrorHandler(500, fn($exception) =>
    App::include('/custom-500.php', ['exception' => $exception]));

// Args passed to App::include() are extracted into the file's
// scope — custom-500.php sees $exception as a local variable.

Recipe K — SEO redirect (old paths to new)

RedirectMatch 301 ^/old-section/(.*)$ /new-section/$1
RewriteRule ^blog/(.*)$ /articles/$1 [R=301,L]

$app->patternRoute('/old-section/(.*)',
    fn($rest, $response) => $response->redirect("/new-section/{$rest}", 301));

$app->patternRoute('/blog/(.*)',
    fn($rest, $response) => $response->redirect("/articles/{$rest}", 301));

Recipe L — Trailing-slash enforcement

RewriteCond %{REQUEST_URI} !(\.[a-zA-Z]+|/)$
RewriteRule (.*) /$1/ [R=301,L]

// 301 to the trailing-slash form for directories under public/.
App::$directory_slash = true;

Recipe summary

Real-world full-.htaccess migration — worked example

A production-style Q&A platform .htaccess with ~30 rewrite rules, headers, charsets, and caching. Each row maps directly to a ZealPHP construct. ✅ = built-in. ⚠ = small custom middleware (on the roadmap). 💡 = PHP-level idiom.

Coverage: ~80% fully supported with no new framework work (every patternRoute + App::include case, redirects, CORS, MIME via static handler, extension resolver, front-controller fallback). ~20% need a small middleware addition or 5-line custom inline.

Apache AllowOverride coverage matrix

Every directive that can appear in a .htaccess file (sourced from Apache's overrides reference), grouped by AllowOverride category. ✅ built-in / ⚠ custom middleware / 💡 PHP-level / ❌ obsolete or unsupported.

AllowOverride All — request shape, server identity, conditionals

AllowOverride AuthConfig — authentication and authorisation

AllowOverride FileInfo — response headers, content negotiation, rewrites, env vars (the big one)

AllowOverride Indexes — directory listings, autoindex, expires headers

AllowOverride Limit — legacy host-based access control

AllowOverride Options — feature toggles and filter chains

Headline coverage

Verdict: ZealPHP covers the practical 80–90% of .htaccess capability that real PHP apps actually use, has clear middleware-extension paths for another 10%, and explicitly disclaims the dead-tech ~5%.

nginx coverage matrix

For users porting from nginx.conf. Sourced from ngx_http_core_module + ngx_http_rewrite_module.

Virtual host & listen

Routing — the location family

Rewrite module

Body, headers, transmission, keep-alive, types, cache, logs, rate limits, auth, proxy, TLS

Headline: nginx-as-front-controller patterns (try_files, location, rewrite, return, error_page) port 1:1 to ZealPHP's native routing — same way .htaccess rewrites do. The "I serve PHP via FastCGI" half of nginx configs is N/A. The proxy/upstream/load-balancing half is intentionally delegated to a real front proxy.

Rewrite rules — internal vs. external

Apache RewriteRule has two flavors that get conflated all the time. The flag in brackets decides whether the URL bar in the user's browser changes.

• No [R] flag = internal rewrite. Apache serves the destination's file but the URL bar still shows the original URL. No Location header sent. The user never sees the internal path. Most SEO-safe, used for friendly URLs over a front controller.
• [R=301] or [R=302] = external redirect. Apache sends a Location header; browser does a fresh request to the destination; URL bar changes. Used to permanently move a page or for vanity short-links.

These map to two different ZealPHP patterns. Don't use header('Location: …') for a non-[R] rewrite — that would expose the internal URL the original rule was hiding.

Custom error pages for legacy apps

Mirror .htaccess's ErrorDocument 404 /custom-404.php with App::setErrorHandler() — see Recipe J above:

$app->setErrorHandler(404, function ($status) {
    // Hand 404s to WordPress so it can render its own theme template.
    return App::include('/wp/index.php');
});

$app->setErrorHandler(500, function ($exception) {
    // Send a JSON envelope to API clients, HTML to browsers.
    $g = ZealPHP\RequestContext::instance();
    if (str_contains($g->server['HTTP_ACCEPT'] ?? '', 'application/json')) {
        return ['error' => 'Internal Server Error', 'trace_id' => uniqid()];
    }
    return App::renderToString('error/500', ['exception' => $exception]);
});

Handlers receive $status, $exception, $request, $response by param injection — same machinery as regular routes. Returns follow the universal return contract. See Responses for details and the docs/error-handling.md deep dive.

AI Config Converter

Paste your .htaccess or nginx config — get a working app.php streamed in real-time. The converter knows about the 12 recipes above, the known limitations matrix, the universal return contract, and the $g-vs-$_* parity rule — so it emits modern App::include() form, refuses unsupported directives explicitly (rather than silently dropping them), and uses $g->get['x'] over $_GET['x']. Powered by gpt-5.4-mini with the full ZealPHP API reference.

// Output will appear here...

# Pipe any config — get app.php on stdout
cat .htaccess | uv run examples/agents/config_converter.py

# Interactive mode
uv run examples/agents/config_converter.py

WordPress example

A complete app.php that runs WordPress on ZealPHP:

<?php
require 'vendor/autoload.php';
use ZealPHP\App;
use ZealPHP\RequestContext;

App::superglobals(true);
App::cgiMode('pool');         // warm FPM-style worker pool (default)
App::cgiPoolMaxRequests(1);   // recycle each request — WP needs a fresh boot
App::$ignore_php_ext = false;

$app = App::init('0.0.0.0', 9501);

// Redirect /wp-admin to /wp-admin/index.php
$app->route('/wp-admin', function ($response) {
    $g = RequestContext::instance();
    $qs = !empty($g->server['QUERY_STRING'])
        ? '?' . $g->server['QUERY_STRING'] : '';
    return $response->redirect('/wp-admin/index.php' . $qs, 301);
});

// Fallback: unmatched URLs → WordPress front controller
// Replaces Apache's: RewriteRule . /index.php [L]
$app->setFallback(fn() => App::include('/index.php'));

$app->run(['task_worker_num' => 0]);

Setup Steps

See the full working example: github.com/sibidharan/zealphp-wordpress

1. Create a ZealPHP project: composer create-project zealphp/project my-wordpress
2. Download WordPress into public/: cd my-wordpress/public && wp core download
3. Configure public/wp-config.php with your database settings
4. Write app.php as shown above
5. Start: php app.php (or php app.php start -p 9501 -d to daemonize)
6. Visit http://localhost:9501/wp-admin/install.php to complete installation

CGI Worker Architecture

App::include() dispatches to two different paths depending on the mode:

• Coroutine mode (App::superglobals(false)) — runs the file in-process via the shared App::executeFile() core. Captures output, applies the universal return contract.
• Superglobals mode (App::superglobals(true)) — dispatches each public/*.php to a warm src/cgi_worker.php drawn from the cgiMode('pool') worker pool (the default), or forwards to an external FastCGI / php-fpm pool under cgiMode('fcgi'). Either way the request runs in a clean, separate PHP process with true global scope — the same model as PHP-FPM / Apache prefork, but the interpreter stays resident between requests instead of cold-starting each time. The worker captures the file's return value over the stderr metadata channel and threads it back through the same contract.

OpenSwoole Worker (long-lived)          Pool Worker (warm, resident)
┌─────────────────────────┐             ┌──────────────────────────┐
│                         │  dispatch   │  php cgi_worker.php      │
│  Route matched          │ ──────────► │  (drawn from warm pool)  │
│  App::include('/x.php') │             │  TRUE global scope:      │
│                         │   stdin     │  ├─ $_SERVER, $_GET, etc.│
│  Serializes context:    │ ──────────► │  ├─ $_COOKIE, $_FILES    │
│  ├─ $_SERVER, $_GET     │  (POST body)│  │                       │
│  ├─ $_POST, $_COOKIE    │             │  ├─ uopz captures:       │
│  └─ Request body        │             │  │  header(), setcookie()│
│                         │   stdout    │  │  http_response_code() │
│  Reads response:        │ ◄────────── │  │                       │
│  ├─ Body from stdout    │             │  ├─ include file.php     │
│  ├─ Metadata from stderr│   stderr    │  │  ← app runs at global │
│  │  (status, headers,   │ ◄────────── │  │    scope              │
│  │   cookies, return    │             │  ├─ resets global scope  │
│  │   value as JSON)     │             │  │  (FPM-style cleanup)  │
│  └─ Applies to response │             │  └─ stays warm for next  │
│                         │             │     request (recycled    │
│                         │             │     after N requests)    │
└─────────────────────────┘             └──────────────────────────┘

What the CGI worker handles

CLI Management

php app.php                     # Start with defaults
php app.php start -p 9501       # Start on port 9501
php app.php start -p 9501 -d    # Start daemonized
php app.php stop                # Stop the server (reads PID file)
php app.php status              # Check if server is running
php app.php start -w 8          # Start with 8 workers
php app.php --help              # Show all options

Performance & Hybrid Mode

CGI backends — host any language

ZealPHP can serve files written in any language that speaks CGI/1.1 — Perl, Python, Ruby, shell scripts, or compiled binaries — side-by-side with your PHP app. Register per-extension backends with App::registerCgiBackend() before $app->run().

Apache / nginx parity table

Worked examples

// .php falls through to App::$cgi_mode (default 'pool' — warm worker pool).
// No registration needed — this is the existing behaviour.
App::processIsolation(true); // enables CGI mode
$app->setFallback(fn() => App::include('/index.php'));

App::registerCgiBackend('.pl', [
    'mode'        => 'proc',
    'interpreter' => '/usr/bin/perl',
]);
// public/info.pl is now executed via /usr/bin/perl
// with the same RFC 3875 CGI env ZealPHP builds for PHP scripts.

App::registerCgiBackend('.py', [
    'mode'        => 'fcgi',
    'address'     => '127.0.0.1:9001',       // or 'unix:/run/python-fpm.sock'
    'fcgi_params' => ['APP_ENV' => 'prod'],   // merged into CGI env (nginx fastcgi_param parity)
]);
// Requests to /hello.py are proxied to the FastCGI server — no process spawn per request.
// Same machinery as the framework-wide App::cgiMode('fcgi') — see #cgi-mode-fcgi below.

App::registerCgiBackend('.cgi', [
    'mode'       => 'proc',
    'exec_paths' => ['/cgi-bin'],   // ExecCGI scope — only execute under /cgi-bin/*
]);
// ZealPHP execs ['path/to/script.cgi'] directly — the OS reads the #! line.
// Script must output CGI/1.1 headers: Content-Type + blank line + body.
// A .cgi requested OUTSIDE /cgi-bin (e.g. an uploaded /uploads/x.cgi) → 403,
// never executed and never served as source.

exec_paths — the ExecCGI scope (default-off)

By default a registered extension does not execute via an implicit URL. exec_paths opts specific URL path prefixes into execution — ZealPHP's parity for Apache's Options +ExecCGI being off by default. A request whose extension is registered but whose URL falls outside every exec_paths prefix is treated as a stray/uploaded script: it is neither executed nor served as source, returning 403 Forbidden. This closes the classic "upload a .py into the docroot and have it execute" hole. Files outside the scope remain reachable via App::include() (which applies its own docroot-containment check).

Implicit URL parity

Implicit routes are registered per registered extension, so GET /cgi-bin/report.py runs public/cgi-bin/report.py through the .py backend with no explicit $app->route() — the same shape as Apache serving a script out of a cgi-bin directory.

cgiScriptAlias() — Apache ScriptAlias parity

App::cgiScriptAlias('/cgi-bin', ['mode' => 'proc', 'interpreter' => '/usr/bin/python3']);
// Any file served under /cgi-bin is executable regardless of its extension.
// Takes the same mode / interpreter / address / fcgi_params config as registerCgiBackend().

pool mode — PHP only constraint

Reader: App::resolveCgiBackend()

App::resolveCgiBackend(string $absPath, string $urlPath = ''): array resolves the backend config and the ExecCGI permission for a path. It returns ['backend' => [...], 'mayExecute' => bool]. Resolution order: cgiScriptAlias() prefixes first (always executable), then the per-extension registry gated by exec_paths, then an unregistered fallback (['mode' => App::$cgi_mode], mayExecute = false). When mayExecute is false the dispatcher returns 403 rather than executing or leaking source.

App::registerCgiBackend('.py', [
    'mode'       => 'fcgi',
    'address'    => '127.0.0.1:9001',
    'exec_paths' => ['/cgi-bin'],
]);

$r = App::resolveCgiBackend('/var/www/app/public/cgi-bin/hello.py', '/cgi-bin/hello.py');
// ['backend' => ['mode' => 'fcgi', 'address' => '127.0.0.1:9001', ...], 'mayExecute' => true]

$r = App::resolveCgiBackend('/var/www/app/public/uploads/hello.py', '/uploads/hello.py');
// ['backend' => [...], 'mayExecute' => false]  ← outside ExecCGI scope → 403

$r = App::resolveCgiBackend('/var/www/app/public/index.php', '/index.php');
// ['backend' => ['mode' => 'pool'], 'mayExecute' => false]  ← unregistered, App::$cgi_mode (default 'pool')

See examples/multi-lang-cgi/ for a runnable demo registering .pl (proc/Perl) alongside the default PHP backend.

Framework-wide cgiMode('fcgi') — front an upstream FPM pool

The per-extension 'fcgi' backend above is for mixing languages. The framework-wide setter App::cgiMode('fcgi') applies the same FastCGI-forwarding behaviour to every public/*.php file — turning ZealPHP into a thin HTTP layer in front of an existing php-fpm pool. Same wire protocol as Apache's mod_proxy_fcgi and nginx's fastcgi_pass, so the FastCGI listener you point at can be php-fpm, HHVM, RoadRunner, or any other FCGI 1.0 backend.

use ZealPHP\App;

App::superglobals(true);          // CGI dispatch path (pool / fcgi)
App::processIsolation(true);
App::cgiMode('fcgi');             // 'pool' (default, warm pool) | 'fcgi'
App::fcgiAddress('127.0.0.1:9000');  // or 'unix:/run/php/php-fpm.sock'

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

When to reach for this:

• You already operate a tuned php-fpm pool (sized for your workload, hooked into your observability stack) and don't want to retire it — ZealPHP adds OpenSwoole's HTTP / WebSocket / coroutine layer on top.
• You want an externally-managed warm pool — let php-fpm be that pool. The FPM master keeps interpreters warm across requests just as ZealPHP's built-in cgiMode('pool') does (~1–3 ms warm either way); the difference is who owns the pool process.
• You're migrating from an nginx → fastcgi_pass deployment and want a drop-in shape change rather than a code rewrite. The fcgi_params array on App::registerCgiBackend() mirrors nginx's fastcgi_param directive.

Under the hood: dispatch lives in App::cgiFcgi(string $path, ?string $address = null, array $extraParams = []), which builds the CGI/1.1 environment via buildCgiEnv(), forwards via ZealPHP\CGI\FastCgiClient::request($params, $stdinBody), and applies the upstream's status code + headers to $g->zealphp_response. A failed connection or FastCgiException from the upstream surfaces as a clean 502 Bad Gateway — same shape Apache and nginx emit when their FCGI upstream is down.

Performance: we don't run PHP at all in this mode — throughput equals whatever your FPM pool delivers minus one local socket hop. We deliberately don't quote a number here: it depends on your FPM pm.max_children, the file under load, and whether you're on Unix sockets vs TCP. The bridge-cost table at /vs-fpm compares the in-process modes (the warm 'pool' and Mixed-mode) and intentionally omits 'fcgi' because the answer is "ask your FPM pool."

cgiMode('fork') — experimental Apache MPM prefork runner

cgiMode('fork') is the fourth .php isolation strategy alongside 'pool', 'proc', and 'fcgi'. Where cgiMode('pool') reuses warm workers and cgiMode('proc') spawns via proc_open (~30–50 ms cold start), the fork runner sits between them: a long-lived fork-master process (src/fork_master.php) binds a UNIX socket and forks a fresh child per request that runs the target .php at true global scope (~1 ms fork cost), then hard-exits. Result: fresh-process correctness (no "Cannot redeclare class") for unmodified WordPress/legacy apps, at fork cost rather than proc_open cost.

Reachability constraint. There is no App::mode() preset for fork and no App::isolation() Fork case — fork is reached exclusively via App::cgiMode('fork') or App::registerCgiBackend('.php', ['mode' => 'fork']). It is .php-only (like 'pool').

Requirements: the PHP build must include ext-pcntl and ext-posix. Verify with php -m | grep -E 'pcntl|posix'.

<?php
require 'vendor/autoload.php';
use ZealPHP\App;

App::superglobals(true);
App::cgiMode('fork');             // experimental: fork-per-request MPM prefork runner
App::$ignore_php_ext = false;     // allow /wp-login.php in URLs

// App::$cgi_fork_max_concurrent = 16; // default; returns 503 when live children hit the cap

$app = App::init('0.0.0.0', 9501);
$app->setFallback(fn() => App::include('/index.php'));
$app->run(['task_worker_num' => 0]);

fork vs pool — when to use which

Backed by src/CGI/ForkPool.php + src/fork_master.php; dispatched via Dispatcher::cgiFork() in src/App.php. Design doc: docs/architecture/2026-06-02-fork-per-request-cgi-pool.md.

What the CGI bridge does for you (security)

Every dispatch mode — the warm 'pool', 'fcgi' forwarding, and the per-language backends — builds the CGI/1.1 environment through the same App::buildCgiEnv() path, so the hardening below applies uniformly. Each item ships a corresponding Apache parity rationale rather than being ZealPHP-specific behaviour.

• httpoxy CVE-2016-5385 mitigation — incoming Proxy: request headers are NOT forwarded as HTTP_PROXY in the CGI env (src/App.php:2830-2836). Apache util_script.c:224-227 parity. Prevents the well-known PHP/Go/Python CGI library family that reads HTTP_PROXY to choose an outbound proxy from being hijacked by a hostile client.
• CGI script timeout — App::$cgi_timeout default 60 s (src/App.php:273). When a CGI subprocess exceeds the budget the worker escalates SIGTERM → SIGKILL and returns control to the request handler. Apache CGIScriptTimeout parity. Override by setting the public static property: App::$cgi_timeout = 120; before App::init().
• CGI Status: header parsed from stdout (src/cgi_worker.php:101-113) — a legacy script that emits Status: 404 Not Found\r\n sets the response status to 404 and the Status: header itself is NOT forwarded to the client. Range-clamped 100–599; non-numeric or out-of-range values fall back to 200. mod_cgi parity.
• stderr drained to elog — anything the subprocess writes to fd 2 (PHP warnings, custom debug, uncaught notices) is routed to /tmp/zealphp/debug.log via the cgi_worker log channel, never leaked into the response body. Prevents the classic "PHP warning rendered into the HTML page" disclosure path.

None of these are opt-in — they're always active on the CGI dispatch path, in every lifecycle mode (the path is no longer gated on processIsolation(true)). There is no flag to disable the HTTP_PROXY strip, the timeout has a floor of 1 s rather than an unbounded option, and stderr always lands in elog.

Coroutine-safe exec

In vanilla OpenSwoole, shelling out (git, ffmpeg, convert, …) via PHP's built-in functions would block the worker — one slow command stalls every coroutine sharing it. ZealPHP solves this: in coroutine mode (the default), overrides intercept shell_exec, exec, system, passthru, and the backtick operator via zealphp_override() (ext-zealphp preferred; uopz_set_return() as fallback), routing them through App::exec() which yields to the scheduler instead of blocking. Legacy code that shells out works safely with no changes.

New ZealPHP-native code should still prefer explicit App::exec(), but the override means unmodified legacy code that shells out stops blocking the worker automatically.

Performance & Hybrid Mode (continued)

For the full performance picture including CGI backends, see the performance page.