App

in package

• ZealPHP

ZealPHP framework core — the single process-wide singleton that owns the OpenSwoole server lifecycle, route table, PSR-15 middleware stack, and all per-request lifecycle configuration.

App::superglobals(false);          // choose lifecycle mode
$app = App::init('0.0.0.0', 8080); // create singleton + install overrides
$app->route('/hello', fn() => 'Hello!');
$app->addMiddleware(new CorsMiddleware());
$app->run();                        // start the OpenSwoole event loop

Table of Contents

Constants

DEFAULT_MAX_COROUTINE  : mixed = 10000

Default per-worker coroutine ceiling applied in run() when the operator sets none (via ZEALPHP_MAX_COROUTINE or $app->run(['max_coroutine' => N])).

DEFAULT_MAX_REQUEST  : mixed = 100000

Default per-worker request-recycle cap (OpenSwoole max_request): the worker exits cleanly and respawns after this many requests, bounding memory growth from leaks. 0 disables recycling (OpenSwoole native semantics) — see resolveMaxRequest() / the ZEALPHP_MAX_REQUEST env. (#449)

ISOLATION_CGI_FCGI  : mixed = 'cgi-fcgi'

ISOLATION_CGI_POOL  : mixed = 'cgi-pool'

ISOLATION_CGI_PROC  : mixed = 'cgi-proc'

ISOLATION_COROUTINE  : mixed = 'coroutine'

Isolation strategy constants — canonical user-facing surface for App::isolation().

ISOLATION_NONE  : mixed = 'none'

KNOWN_METHODS  : array<int, string> = [ 'GET', 'HEAD', 'POST', 'PUT', 'DELETE', 'OPTI...

Methods ZealPHP recognises. A request whose method is outside this set gets 501 Not Implemented (Apache: M_INVALID → HTTP_NOT_IMPLEMENTED, server/protocol.c:1253). Standard RFC 9110 methods plus the common WebDAV verbs Apache registers in ap_method_registry_init(). A recognised method that has no matching route still flows through to 404/405/fallback.

MODE_COROUTINE  : mixed = 'coroutine'

MODE_COROUTINE_LEGACY  : mixed = 'coroutine-legacy'

MODE_LEGACY_CGI  : mixed = 'legacy-cgi'

High-level mode presets — canonical user-facing surface for App::mode().

MODE_MIXED  : mixed = 'mixed'

LIFECYCLE_MODE_NAMES  : mixed = ['coroutine', 'coroutine-legacy', 'legacy-cgi',...

Lifecycle modes a user might mistakenly pass as a route backend. Rejected with a message pointing at the separate-process model.

REASON_PHRASES  : mixed = [ // 1xx Informational 100 => 'Continue', 101 =...

IANA-registered HTTP status reason phrases (RFC 9110 §15).

ROUTE_BACKEND_MODES  : mixed = ['pool', 'proc', 'fork', 'fcgi']

The four CGI dispatch strategies a per-route backend: may name — the CGI-ISOLATION family. Excludes the COROUTINE-SCHEDULER family (coroutine/coroutine-legacy/legacy-cgi/mixed), which is a process-wide lifecycle decision frozen at $server->start() and cannot be chosen per route. See normalizeBackendConfig()'s guard.

WHEN_MEMO_MAX  : mixed = 4096

Upper bound on the App::when per-path memo (memory-exhaustion guard).

Properties

$access_log_format  : string

Apache LogFormat "...". Format string used by access_log() to render each request line. Tokens (Apache mod_log_config subset):

$admin_checker  : callable|null

Callback consulted by ZealAPI::isAdmin(). Signature: fn(): bool.

$allow_encoded_slashes  : bool

Apache AllowEncodedSlashes — when false (default, matching Apache), a request whose RAW (pre-decode) path contains an encoded slash (%2F/%2f) is refused with 404 before route matching. Apache's unescape_url() forbids AP_SLASHES by default; we mirror that. Set true to permit encoded slashes (they are then decoded to / like any other octet).

$api_null_not_found  : bool

#347 — the 404 {"error":"method_not_found"} envelope for a ZealAPI handler that returns null with NO output, NO explicit status and NO streaming. **Mode-aware (corrected rule):** it applies ONLY to **per-method** dispatch ($get/$post/…) — a method handler that ran and produced nothing. A **filename-match** handler ($list, serving all methods) returning null is an intentional **empty 200** (native-PHP parity — an empty-set / infinite-scroll tail), never a 404. A method with no handler at all already 405s before this point. Default ON.

$api_warn_collisions  : bool

Log warnings when a ZealAPI filename collides with an HTTP method keyword (get.php defining $get) or when a filename-matched handler shadows per-method handlers in the same file. Default ON so new apps surface mistakes; set to false (or 'api_warn_collisions' => false in the run() config) for legacy codebases that knowingly use method names as filenames.

$auth_checker  : callable|null

Auth-hook callbacks consulted by ZealAPI::isAuthenticated(), ::isAdmin(), and ::getUsername() so the framework's built-in file-based API layer can delegate auth questions to whatever auth system the app uses (Symfony Security, Auth0, the SelfMadeNinja stack, a custom $_SESSION['user'] check, etc.) without subclassing or monkey-patching ZealAPI itself.

$block_dotfiles  : bool

Block any path containing a dotfile component (.git, .env, .htaccess, etc.). Apache convention.

$boot_env  : array<string, string>

Process environment captured at boot (real getenv()), before the per-coroutine putenv/getenv overrides are installed in Mode 4. The overridden \ZealPHP\zeal_getenv falls back to this for variables not set request-scoped via \ZealPHP\zeal_putenv.

$canonical_name  : string|null

Apache ServerName www.example.com:443. The canonical host the server advertises in absolute redirects (and other absolute URL builders) when $use_canonical_name is true. Include scheme-port if relevant; the raw value is returned as-is by App::canonicalHost().

$cgi_backend_aliases  : array<string, array{mode: string, interpreter?: string, address?: string, fcgi_params?: array}>

Named CGI backend aliases for the per-route backend: option, registered via App::cgiBackendAlias(). Maps an alias name to a normalised backend config (the same shape resolveCgiBackend() returns, minus exec_paths).

$cgi_backends  : array<string, array{mode: string, interpreter?: string|null, address?: string, fcgi_params?: array, exec_paths?: array}>

Per-extension CGI backend registry. Apache AddHandler/ProxyPassMatch + nginx fastcgi_pass-per-location parity.

$cgi_fork_instance  : ForkPool|null

Per-worker ForkPool singleton for cgiMode('fork') — the fork-master subprocess. Lazy-spawned on first dispatch in this OpenSwoole worker (same per-worker ownership rationale as $cgi_pool_instance).

$cgi_fork_max_concurrent  : int

Live-child concurrency cap for cgiMode('fork') — the fork-master refuses to fork past this many simultaneous children (fork-bomb guard + backpressure).

$cgi_fork_max_concurrent_set  : bool

$cgi_mode  : string

How a process-isolated legacy include is dispatched, when processIsolation() is on:

$cgi_mode_set  : bool

"Explicitly set by a fluent setter" flags for the env-overridable CGI knobs. App::resolveCgiEnv() applies a ZEALPHP_CGI_* value only when the matching flag is false — so explicit code config always wins over the environment, which in turn wins over the hardcoded default.

$cgi_pool_env_allowlist  : array<int, string>

Optional strict env allowlist for cgiMode('pool') subprocesses (WorkerPool::filterSubprocessEnv). Empty (default) = pass the parent environment through to the subprocess (legacy-app compatibility) MINUS the request-controlled HTTP_PROXY (httpoxy). Set via App::cgiPoolEnvAllowlist([...]) to a list of exact names / PREFIX* globs to restrict what secrets the long-lived subprocess inherits; ZEALPHP_POOL_MAX_REQUESTS is always passed. Per-request CGI vars travel over the IPC frame, not this env, so a strict allowlist doesn't lose them.

$cgi_pool_instance  : WorkerPool|null

Per-worker WorkerPool singleton for cgiMode('pool'). Lazy-spawned on first dispatch in this OpenSwoole worker. Held here (not on a Store) because each OpenSwoole worker owns its own subprocess pool — proc resources don't share across workers.

$cgi_pool_max_requests  : int

Per-subprocess recycle threshold for cgiMode('pool'). After this many requests, the subprocess exits cleanly and the pool spawns a fresh replacement — FPM pm.max_requests parity, bounds memory leak from long-running plugin code. Set to 1 to recycle every request (true fresh-process semantics; same isolation as cgiMode('proc') but with the pool managing spawn-cost amortisation).

$cgi_pool_max_requests_set  : bool

True once cgiPoolMaxRequests() set the recycle count explicitly. The mode() presets consult this so a mode('legacy-cgi') default (recycle=1) never clobbers an explicit user choice, regardless of call order.

$cgi_pool_size  : int

Subprocess count for cgiMode('pool') — the native FCGI-style worker pool. Each OpenSwoole worker process spawns this many persistent PHP subprocesses on first dispatch (lazy). FPM pm.max_children parity: sets the per-worker concurrency cap. Default 4 — balances spawn cost with concurrency for typical web workloads.

$cgi_pool_size_set  : bool

$cgi_script_aliases  : array<string, array{mode: string, interpreter?: string|null, address?: string, fcgi_params?: array}>

ScriptAlias-style CGI path registry (Apache ScriptAlias parity). Maps a normalised URL prefix (leading slash, no trailing slash) to a backend config. Any file served under a registered prefix is treated as executable regardless of its extension.

$cgi_session_auto_start  : bool

legacy-cgi only: eagerly mint a session id + Set-Cookie on a FIRST-time visitor (no incoming PHPSESSID) BEFORE the CGI subprocess runs (#108).

$cgi_subprocess_autoload  : bool

Whether cgi_worker.php (proc-mode subprocess entry) loads Composer's vendor/autoload.php on startup. Default false — restores the pre- v0.2.20 behaviour where the subprocess runs at true global scope with NO ZealPHP framework loaded, suitable for unmodified WordPress / Drupal.

$cgi_timeout  : int

Maximum seconds to wait for a CGI subprocess (proc mode) to produce its metadata line on stderr. After this deadline the child receives SIGTERM; if it does not exit within 5 s it receives SIGKILL. Matches Apache's CGIScriptTimeout directive. Default 60 s.

$cgi_timeout_set  : bool

$coproc_implicit_request_handler  : bool

Enable the legacy CGI request handler for public/*.php paths.

$coroutine_cwd_isolation  : bool

Per-coroutine WORKING-DIRECTORY isolation (#323). chdir() is a process-level syscall, so under coroutine concurrency one request's chdir() (or the framework's own executeFile() chdir-to-script-dir) changes the CWD of every concurrently-running peer — racy relative includes / fopen across the whole worker. When ON (and ext-zealphp 0.3.35+ is loaded), the scheduler hooks save each coroutine's cwd on yield (re-parking the worker baseline so peers start clean) and restore it on resume — chdir() becomes per-coroutine, like PHP-FPM's per-process CWD. Auto-enabled by App::mode('coroutine-legacy') (opt out with env ZEALPHP_CWD_ISOLATION_DISABLE=1); off by default elsewhere (coroutines that never chdir cost one getcwd+strcmp per yield when on, zero when off).

$coroutine_globals_isolation  : bool

Per-coroutine $GLOBALS isolation via ext-zealphp's zealphp_coroutine_globals(). When enabled, each coroutine gets its own snapshot of EG(symbol_table) swapped in on yield/resume — so $GLOBALS['app_state'] and global $foo; writes never race across concurrent coroutines.

$coroutine_isolated_superglobals  : bool

True when ext-zealphp's per-coroutine superglobal isolation is active.

$coroutine_libxml_isolation  : bool

Per-coroutine libxml_use_internal_errors() FLAG isolation — the libxml error-buffering flag is process-global (measured 128/250 leaks).

$coroutine_locale_isolation  : bool

Per-coroutine LOCALE isolation — setlocale() is process-global (string casing, number/date formatting), so one request's locale change leaks into every concurrently-running peer mid-request. When ON (ext-zealphp 0.3.38+), the scheduler hooks save each coroutine's locale on yield (re-parking the worker baseline captured at enable time — a boot-time setlocale() before App::run() IS the baseline) and restore it on resume. Auto-enabled by App::mode('coroutine-legacy') (opt out with env ZEALPHP_LOCALE_ISOLATION_DISABLE=1); off by default elsewhere.

$coroutine_mbenc_isolation  : bool

Per-coroutine mb_internal_encoding() isolation — the mbstring current internal encoding is process-global; legacy code sets it before string work (measured 173/250 leaks at 49-way concurrency). ext-zealphp 0.3.45+; auto-refuses when mbstring is absent. Auto-enabled by App::mode('coroutine-legacy') (opt out with env ZEALPHP_MBENC_ISOLATION_DISABLE=1); off by default elsewhere.

$coroutine_statics_isolation  : bool

Stage 5 — per-coroutine FUNCTION-local static $x isolation via ext-zealphp's zealphp_coroutine_statics(). This is the LAST request-state primitive that previously leaked across coroutines (everything else — superglobals, class statics, $GLOBALS, constants, ini_set, putenv — is already isolated). When enabled, the on_yield hook snapshots every instantiated function/method's live static table per coroutine and restores THIS coroutine's values on resume — the same snapshot/restore model already proven for class statics. Cooperative scheduling makes it correct: a coroutine writes its statics after its own restore and reads them before its next yield, so values never bleed.

$coroutine_tz_isolation  : bool

Per-coroutine date_default_timezone_set() isolation — the default timezone is process-global; WordPress-class apps set it per request (core boot reads the site option), so one request's timezone leaks into every concurrently-running peer (measured 179/250 at 49-way concurrency). Same stage shape as locale/umask (ext-zealphp 0.3.45+, via the engine's own getter/setter pair). Auto-enabled by App::mode('coroutine-legacy') (opt out with env ZEALPHP_TZ_ISOLATION_DISABLE=1); off by default elsewhere.

$coroutine_umask_isolation  : bool

Per-coroutine UMASK isolation — umask() is process-global file-mode state; one request's umask(0077) changes every peer's file creation mid-request. Same stage shape as locale/CWD (ext-zealphp 0.3.38+; the umask read+re-park is a single syscall). Auto-enabled by App::mode('coroutine-legacy') (opt out with env ZEALPHP_UMASK_ISOLATION_DISABLE=1); off by default elsewhere.

$cwd  : string

Absolute working directory the framework boots in. Resolved at boot via realpath(__DIR__ . '/..') and exposed read-only for handlers that need to build paths relative to the project root (e.g.

$default_charset  : string

Apache AddDefaultCharset. Stored here for consumers (e.g. a future CharsetMiddleware) that want a server-wide default charset to append to text-ish Content-Type headers.

$default_mimetype  : string

Apache DefaultType / PHP default_mimetype. The Content-Type applied by CharsetMiddleware to a response that doesn't set one itself (mod_php sends text/html by default). Set to '' to leave untyped responses untouched.

$default_php_self  : string|null

Override value for $_SERVER['PHP_SELF'] and friends. null means "use the request URI verbatim", which is the normal Apache/nginx convention. Apps that need a stable PHP_SELF (legacy WordPress plugins, etc.) can pin it here.

$define_isolation  : bool

Per-request define() isolation. When true, constants defined during a request are tracked and removed at request end. Boot-time constants (PHP_VERSION, extension defines, autoloaded class constants) survive.

$dev_reload  : bool|null

Dev route hot-reload toggle. When true, each worker polls route/*.php mtimes and calls reloadRoutes() on change (no process restart). null resolves to the ZEALPHP_DEV env var at run(). OFF in production (the route table stays master-loaded + COW-shared). Set via App::devReload().

$directory_index  : array<int, string>

Apache DirectoryIndex — file names tried in order when a directory is requested.

$directory_slash  : bool

Apache DirectorySlash equivalent — redirect /foo → /foo/ when foo is a directory.

$display_errors  : bool|null

Whether framework error pages render the captured exception + stack trace inline. Secure-by-default: null (the default) resolves at runtime to the ZEALPHP_DEV env var — OFF in production, so 5xx pages show a generic message and never leak traces/secrets (#412). Call App::displayErrors(true) for the inline-trace development view; an explicit setter call always wins over the env resolution.

$document_root  : string

Apache DocumentRoot equivalent. Relative values (the default) are resolved against App::$cwd; absolute values are used as-is. Drives App::include() path resolution and the implicit /{file}/{dir/uri} routes.

$enable_coroutine_override  : bool|null

OpenSwoole enable_coroutine server-setting override. null means "follow !$superglobals" (true → coroutine-per-request, false → one synchronous request at a time per worker). Set via App::enableCoroutine(bool). Combining true with $superglobals=true is unsafe — process-wide $_GET/$_POST/$_SESSION will race across concurrent coroutines; the helper warns at run() time.

$fcgi_address  : string

FastCGI backend address used when App::cgiMode() === 'fcgi'.

$fcgi_address_set  : bool

$file_etag  : bool

Apache FileETag. When false, ETagMiddleware emits no ETag header and never returns 304 (equivalent to FileETag None). Default true.

$function_isolation  : bool

Per-request function/class/include isolation via ext-zealphp's zealphp_process_state_snapshot() / zealphp_process_state_clean().

$global_scope_include  : bool|null

Stage 8 — true-global-scope request include (coroutine-legacy). When on (and ext-zealphp exposes zealphp_require_global()), App::include() runs the target file at TRUE global scope so a bare file-scope $x = ... — and every transitive require_once — binds to $GLOBALS instead of the executeFile() method frame. This is what lets unmodified require_once- bootstrap apps (WordPress's $menu/$submenu/$_wp_submenu_nopriv, built bare at file scope in wp-admin/includes/menu.php) render in **coroutine-legacy** in-process mode, where the request entry runs inside a PHP method and those vars would otherwise be method-local.

$hook_all_override  : bool|int|null

OpenSwoole\Runtime::enableCoroutine($flags) override. Same shape as App::hookAll() input: null → follow !$superglobals (HOOK_ALL when coroutine mode, 0 in superglobals mode); true → HOOK_ALL; false → 0; int → explicit bitmask. PDO is intentionally NOT hooked in OpenSwoole 22.1 / 26.2 regardless of this flag.

$hook_exec  : bool|null

Toggle the uopz override of the exec family (backtick / shell_exec / exec / system / passthru) so they yield via OpenSwoole's coroutine scheduler instead of blocking the worker.

$hook_exit  : bool|null

Toggle the ext-zealphp interception of exit()/die() so a userland exit inside a coroutine throws ZealPHP\HaltException (which extends \Error, so the ubiquitous try { … exit; } catch (\Exception) legacy-router idiom cannot swallow the normal exit and turn it into a 500 — issue ext#47; FreshRSS/DokuWiki/CodeIgniter). The framework's halt-aware sites flush the buffered output as the body. null (default) resolves to "on when the coroutine scheduler is active" (enableCoroutine effective) at App::run(); a non-null value forces it. Requires ext-zealphp 0.3.48+ (zealphp_exit_hook); a no-op otherwise. Env opt-out: ZEALPHP_EXIT_HOOK_DISABLE=1.

$hostname_lookups  : bool

Apache HostnameLookups On|Off. When true, the framework populates $g->server['REMOTE_HOST'] via gethostbyaddr($g->server['REMOTE_ADDR']) on each request. **WARNING**: this performs a blocking reverse-DNS lookup per request (mitigated by OpenSwoole's coroutine hook converting it to a non-blocking async resolve, but still a measurable per-request cost). Off by default — Apache's own default since 1.3.

$ignore_php_ext  : bool

When true (default), URLs ending in .php get a 403. The framework encourages extensionless URLs as the canonical public surface (matches Apache RewriteRule \.php$ - [F] parity). Set false to allow direct *.php routing — useful when porting an existing app that links to /foo.php from external sources.

$include_isolation  : bool

Per-request require_once cache reset. Clears EG(included_files) so files loaded via require_once on request N re-execute on request N+1.

$initial_error_reporting  : int

Initial error_reporting level captured at boot — referenced by the per-coroutine override.

$keep_globals  : bool

Keep user-defined $GLOBALS across requests within the same worker.

$limit_request_field_size  : int

Apache LimitRequestFieldSize — maximum byte length of a single request header line. **NOT enforced by ZealPHP.** OpenSwoole's C-layer HTTP parser owns all wire-level framing; ZealPHP only sees the already-parsed $request->header array. The http_header_buffer_size option was explicitly NOT passed to OpenSwoole (its option validator rejects it at boot — see App::run() ~line 3748). Changing this value has no effect on the actual per-header byte limit, which is governed by OpenSwoole's global header-buffer size (~8 KiB default). This property is retained for documentation and future compatibility only.

$limit_request_fields  : int

Apache LimitRequestFields — maximum number of request header fields a single request may carry. Enforced at the PHP application layer: requests carrying more than this many headers are rejected with 400 before route dispatch. Set to 0 to disable the check (unlimited). Default 100 matches Apache's compiled-in default.

$limit_request_line  : int

Apache LimitRequestLine — maximum byte length of the HTTP request line (method + URI + protocol). **NOT enforced by ZealPHP.** OpenSwoole's C parser reads the request line before any PHP code runs; there is no per-request-line cap that ZealPHP can apply after the fact. OpenSwoole's global http_header_buffer_size governs this limit at the wire level.

$middleware_aliases  : array<string, MiddlewareInterface|callable>

Named middleware registry — Traefik's "named & shared" middleware and Laravel's route-middleware aliases. Maps a short name to either a ready MiddlewareInterface instance or a factory callable(...$args) that returns one. Populated by App::middlewareAlias() at boot; resolved to instances once at App::run() (single-coroutine, so the hot path never does a registry lookup or instantiation). Reused across routes — middleware objects MUST be stateless (request state lives in $g/RequestContext, never on the middleware) because one instance is shared by every concurrent coroutine that uses the alias.

$middleware_stack  : StackHandler|null

The PSR-15 middleware stack handler, built during App::run() from the registered middleware list. null before run(). Generally read via the public App::middleware() accessor; this property is public for advanced introspection (e.g. /healthz dumps).

$middleware_wait_stack  : array<int, MiddlewareInterface>

Middleware queued via App::addMiddleware() BEFORE App::run().

$path_info  : bool

Apache PATH_INFO — when /script.php/extra/path, expose /extra/path as PATH_INFO.

$port  : int

$preload_classes  : array<int, class-string>

Extra classes to compile at worker start so they are NEVER cold-autoloaded under request concurrency. APPENDED to the framework's own request-path warmup set (see preloadRequestPathClasses()).

$preload_classmap  : bool

When true, warm EVERY class in Composer's classmap in the MASTER process (before $server->start() forks the workers), so a user app's own controllers/services (autoloaded on demand, deep inside handlers — "the app is just the server") are born LINKED and copy-on-write-forked into every worker, never compiled on the concurrent cold path. This is the structural fix for the present-but-unlinked inheritance race: the whole dependency graph is bound in a single process with NO coroutine scheduler, so nothing can yield and let a worker interleave a cold compile. Same idea as PHP's opcache.preload. Validated: 0 failures across cold bursts with the framework's own onWorkerStart preload disabled (classmap-only).

$preload_dirs  : array<int, string>

Source directory trees to warm at worker start (PSR-4 roots / app source whose symbols a registered autoloader can resolve). Each .php file's declared symbols are extracted via the tokenizer and autoloaded+linked single-coroutine. Append via App::preloadDir().

$process_isolation  : bool|null

Per-include CGI process-isolation override. null means "follow $superglobals" (true → CGI subprocess via cgi_worker.php; false → in-process via executeFile()), which preserves today's default coupling. Set via App::processIsolation(bool) — see that method for the trade-offs. App::run() resolves this into the backing $coproc_implicit_request_handler flag right before the server starts.

$reloading  : bool

True only while App::reloadRoutes() is re-including route/*.php files.

$run_has_started  : bool

Set true at the top of App::run() so the four lifecycle setters (superglobals, processIsolation, enableCoroutine, hookAll) can refuse mutations made AFTER the server has booted.

$sapi_name  : string|null

mod_php-parity SAPI identity for the php_sapi_name() override. Default null returns the real PHP_SAPI ("cli") — no behavior change. Set to a web SAPI string (e.g. 'apache2handler', 'fpm-fcgi') so legacy code branching on php_sapi_name() takes its web path. The PHP_SAPI *constant* is unaffected (uopz cannot redefine it). Configure via App::sapiName() before App::init().

$server  : Server|Server|null

The active OpenSwoole server instance after App::run() constructs it; null before run(). Returned as a WebSocket\Server when any App::ws() route was registered (the framework upgrades from Http\Server automatically), Http\Server for pure HTTP apps.

$server_admin  : string|null

Apache ServerAdmin webmaster@example.com. When set, the framework's default 500/error page mentions this contact. null disables the contact line.

$server_tokens  : string

Apache ServerTokens. Controls how much detail the X-Powered-By response header advertises: 'Full' (default) → ZealPHP + OpenSwoole 'Prod' / 'Major' / 'Minor' / 'Min' / 'OS' → ZealPHP 'None' (or '') → header omitted entirely (info-leak hardening) Set via App::serverTokens() before App::init().

$session_data_size  : int

Maximum serialized session size in bytes when using TableSessionHandler.

$session_handler  : string|SessionHandlerInterface|null

Session storage backend. One of: - null (default) — the framework inline **file** path in ALL modes (flock read-merge-write under $session_save_path). #295: deliberately NOT auto-promoted to TableSessionHandler; the unconfigured default is file-backed everywhere. Opt into a concurrent-safe backend explicitly.

$session_lifecycle  : bool

Whether ZealPHP's per-request session lifecycle runs. Default true: the SessionManager / CoSessionManager OnRequest wrapper reads the PHPSESSID cookie, calls zeal_session_start(), optionally emits the Set-Cookie header, and closes the session at request end. Set to false when another framework (e.g. Symfony's NativeSessionStorage via the zealphp-symfony bridge) owns the session lifecycle — ZealPHP then skips the session-specific work but still does request-context setup ($g->openswoole_request, $g->zealphp_response, error-stack reset, etc.).

$session_max_rows  : int

Maximum concurrent sessions in OpenSwoole\Table when using TableSessionHandler. Default 65536 (64K) — accommodates medium-scale deployments without re-tuning. Each row costs `$session_data_size + ~64 bytes` of shared memory (one allocation per OpenSwoole server, NOT per worker). Default config = 64K × 16KB ≈ 1 GB shared memory.

$session_save_path  : string

File-backing directory for session storage. Default /var/lib/php/sessions (matches PHP's default). Used by FileSessionHandler and TableSessionHandler's file backing layer.

$session_strict_mode  : bool

PHP session.use_strict_mode parity (#244). When true (the default — security-first) a CLIENT-SUPPLIED session id (from a PHPSESSID cookie or query param) whose backing store loads an EMPTY session is treated as untrusted: the session managers mint a fresh server-generated id and switch the client to it. This defeats session FIXATION — an attacker who plants a known id into the victim's browser can no longer have it promoted to an authenticated session, because the framework rotates any unrecognised id before the victim ever authenticates under it. A well-formed id that DOES resolve to a non-empty stored session is preserved unchanged.

$session_ttl  : int

Session TTL in seconds. Default 7200 (2 hours — modern-app reasonable; PHP's stock 1440 / 24 min is too short for typical workflows).

$silent_redeclare  : bool

Stage 3 — silent-redeclare opcode hooks. When enabled, ext-zealphp's ZEND_DECLARE_FUNCTION / ZEND_DECLARE_CLASS / _DELAYED opcode handlers check if the target symbol already exists in EG(function_table) / CG(class_table). If it does, the opcode is silently skipped instead of throwing E_COMPILE_ERROR ("Cannot redeclare …"). First declaration wins — matches what FPM gets "for free" by forking a fresh process per request.

$static_handler_locations  : array<int, string>

Static handler URL-prefix whitelist. Empty = serve any path under document_root (Apache default).

$strip_trailing_slash  : bool

Apache RewriteCond %{REQUEST_FILENAME} !-d + RewriteRule ^(.+)/$ /$1 [R=301,L].

$superglobals  : bool

Per-request lifecycle mode (the dial that picks $g storage + SessionManager + enable_coroutine + HOOK_ALL default). See the "Lifecycle modes" matrix in CLAUDE.md — short version:

$trace_enabled  : bool

Apache TraceEnable — defaults to OFF for security. When false (default) ResponseMiddleware refuses HTTP TRACE with 405 regardless of any matching route definition. Set to true only if you know you need TRACE.

$trusted_proxies  : array<int, string>

CIDR list of proxy IPs whose X-Forwarded-For / X-Real-IP headers App::clientIp() will trust. Empty (the default) means no proxies trusted — App::clientIp() always returns REMOTE_ADDR. Critical for production deploys behind Traefik/Caddy/nginx; without it rate limiters and access logs see the proxy IP instead of the real client.

$use_canonical_name  : bool

Apache UseCanonicalName On|Off. When true and $canonical_name is set, App::canonicalHost() returns the canonical name; otherwise it returns the request Host header. Default false (Apache's default since 2.0).

$username_provider  : callable|null

Callback consulted by ZealAPI::getUsername(). Signature: fn(): ?string.

$when_middleware  : array<int, MiddlewareInterface|string>}>

Path-scoped middleware registry — App::when($path, $middleware). Each entry scopes a chain to a URL path prefix (or a #...# PCRE), and runs for EVERY request whose normalized path matches — route or api alike, since api endpoints are just /api/... URLs on the same stack. Stored in registration order (first registered = outermost). Raw specs here; resolved to instances at App::run() into $when_middleware_compiled.

$when_middleware_compiled  : array<int, MiddlewareInterface>}>

Boot-compiled App::when chains (alias→instance), read-only at request time so the hot path never does a registry lookup or new.

$when_middleware_memo  : array<string, array<int, MiddlewareInterface>>

Per-normalized-path memo of the flattened matching when chain (the registry is immutable after boot, so this is a write-once-per-path cache; concurrent same-path writes are idempotent). Capped at WHEN_MEMO_MAX entries so an attacker spraying distinct paths can't grow it without bound — past the cap, paths simply recompute the (cheap) prefix scan.

$autoloadSerializerInstalled  : bool

True once the per-worker coroutine autoload serializer is installed.

$bootedAt  : int|null

Unix timestamp the master process booted at (set by run()).

$host  : string

Bind address for the OpenSwoole server (e.g. '0.0.0.0' or '127.0.0.1'). Set in __construct() from App::init().

$processBootWired  : bool

True once the onWorkerStart hook for process-pool is wired.

$processHandlers  : array<string, array{callable: callable, workers: int, coroutine: bool}>

$pubsubBootWired  : bool

True once the onWorkerStart hook for pubsub/streams is wired (one-time guard).

$pubsubRegistry  : array<string, array<int, callable>>

$reliableRegistry  : array<string, array<int, array{group: string, handler: callable, blockMs: int, batchSize: int}>>

$route_baseline  : MiddlewareInterface|callable>, backend_aliases?: array}>}|null

Snapshot of the route/middleware registries taken at App::run() *before* the route/*.php files + implicit routes are loaded — i.e. just the app.php-defined explicit routes/aliases/scopes. App::reloadRoutes() restores this baseline, then re-runs the file-based registration, so a route-file edit can be picked up without restarting the worker. Null until run() snapshots it.

$routes  : array<int, MiddlewareInterface|string>, backend?: array{mode: string, interpreter?: string, address?: string, fcgi_params?: array}|null}>

$routes_by_exact_method  : array<string, array<string, MiddlewareInterface|string>, backend?: array{mode: string, interpreter?: string, address?: string, fcgi_params?: array}|null}>>

$routes_by_method  : array<string, array<int, MiddlewareInterface|string>, backend?: array{mode: string, interpreter?: string, address?: string, fcgi_params?: array}|null}>>

$signalHandlers  : array<int, array<int, array{handler: callable, worker_only: bool}>>

$task_worker_num  : int

Resolved task-worker count after run() reads CLI/env/settings. Zero when task workers are disabled.

$worker_num  : int

Resolved worker counts after run() reads CLI/env/settings.

$workerStartedAt  : float

Unix timestamp (float) of the moment this worker's onWorkerStart callback finished — used by App::stats() to compute per-worker uptime. Zero until the first worker start fires.

$workerStartHooks  : array<int, callable>

$workerStopHooks  : array<int, callable>

$ws_routes  : array<string, array{message: callable, open: callable|null, close: callable|null}>

$access_log_format_compiled  : array<int, array{kind: string, arg?: string}>|null

Parsed format spec cache (token list). Filled lazily by formatAccessLogLine() the first time it sees a given format string. Resets when accessLogFormat() is reassigned via the fluent setter.

$configMap  : array<string, string>

ZealPHP config keys recognized in the run() $settings array.

$error_handlers  : array<int, array{handler: callable, param_map: array, raw: bool}>

Status -> custom error handler registry (key 0 = catch-all).

$fallback_handler  : array<string, mixed>|null

$fatal_guard_inflight  : array<int, Response>

#338 — in-flight raw responses, per worker process. A worker-killing FATAL (E_COMPILE_ERROR / E_ERROR / …) never reaches the normal emit path, so the client connection — held open by the master's reactor — would hang until the CLIENT's timeout (HTTP 000). Apache/mod_php answers 500. The session managers track every request's raw OpenSwoole response here and release it on normal completion; the native shutdown guard below answers whatever is left when a fatal tears the worker down. Coroutine mode can hold several entries at once — one fatal kills them all, so all of them get the 500.

$instance  : self|null

$overridesRegistered  : bool

Guard preventing registerAllOverrides() from installing uopz/zealphp built-in overrides more than once per process.

$resolved_session_handler  : SessionHandlerInterface|null

Memoised resolution of {@see $session_handler} (see resolveActiveSessionHandler).

$session_handler_resolved  : bool

Whether {@see $resolved_session_handler} has been computed yet.

Methods

__wakeup()  : mixed

accessLogFormat()  : string

Apache LogFormat. Resets the compiled-spec cache on set.

addMiddleware()  : void

addProcess()  : void

Register a long-running sidecar process — runs alongside the HTTP/WS server, managed by the OpenSwoole master (same fate-sharing: dies when the server stops, respawned on graceful reload). Different from task workers (which are queue consumers) and worker hooks (which run inside HTTP workers); these are independent processes for background work like log shippers, file watchers, scheduled-job runners, OAuth token refreshers, etc.

adminChecker()  : callable|null

Register a callback that ZealAPI::isAdmin() consults.

adoptRequestContext()  : void

#42 — make the CURRENT (child) coroutine inherit the spawning request's context. Two layers: RequestContext::instance() walks the parent-coroutine chain automatically (so $g is the request's), and — in coroutine-legacy, where $g->server et al. are live aliases of the process superglobals — zealphp_superglobals_adopt() (ext-zealphp 0.3.43+) gives this coroutine its OWN superglobal snapshot lane: its first yield CAPTURES the live view (the spawning request's state) without clearing it, so $_SERVER/$_GET/… survive the child's own yields and the parent is never stolen from. Safe no-op outside a coroutine or without the ext function. Called automatically by App::go() / App::parallel() / App::parallelLimit().

after()  : int

One-shot timer: calls $fn once after $ms milliseconds.

any()  : void

apiNullNotFound()  : bool

#347 — whether a ZealAPI handler returning null with no output, no explicit status and no streaming yields the Apache-parity 404 {"error":"method_not_found"} envelope instead of 200 + empty body. Default true. No-arg call returns the current value.

apiWarnCollisions()  : bool

Whether ZealAPI logs a warning when a filename collides with an HTTP method keyword (e.g. get.php defining $get) or a filename-matched handler shadows per-method handlers. Default true. No-arg call returns the current value.

applySignalHandlersFor()  : void

Internal: wire registered signal handlers into the OpenSwoole process lifecycle. Called from App::run() (master) and via onWorkerStart (workers).

authChecker()  : callable|null

Register a callback that ZealAPI::isAuthenticated() consults.

blockDotfiles()  : bool

Block any request whose path contains a dotfile component (.git, .env, .htaccess, etc.) with 403. Default true — matches Apache's convention of not serving hidden files. No-arg call returns the current value.

buildCgiEnv()  : array<string, string>

Build the OS-level environment array passed to the CGI subprocess.

canonicalHost()  : string

Canonical host for absolute URL building. Returns $canonical_name when useCanonicalName() is on AND $canonical_name is set; otherwise returns the request Host header (falling back to SERVER_NAME, then ''). Used by absolute-redirect builders that need to decide between the configured server name and the client-provided Host.

canonicalName()  : string|null

Apache ServerName. Canonical host advertised in absolute redirects when useCanonicalName() is on. Pass null/'' to clear.

cgiBackendAlias()  : void

Register a named CGI backend alias for the per-route backend: option — the App::middlewareAlias() of the CGI dispatch world. Lets a route say backend: 'wp-fork' instead of repeating an inline config.

cgiForkMaxConcurrent()  : int

Max concurrent cgiMode('fork') children — a per-request fork ceiling, NOT the pre-spawned cgiPoolSize(). Default 16. No-arg returns the current value; with-arg sets and returns it. Env: ZEALPHP_CGI_FORK_MAX_CONCURRENT (applied at boot unless set explicitly).

cgiMode()  : string

Select how a process-isolated legacy include is dispatched: 'pool' (default) — pre-spawned PHP worker pool, mod_php-style isolation, ~1-3 ms warm.

cgiOwnsSessions()  : bool

True when the CGI subprocess is the sole owner of the per-request session lifecycle — superglobals(true) + processIsolation(true).

cgiPoolEnvAllowlist()  : array<int, string>

Strict environment allowlist for cgiMode('pool') subprocesses — exact names and/or PREFIX* globs. A no-arg call returns the current list; a one-arg call sets it. Empty (default) passes the parent env through (legacy-app compatibility) minus the httpoxy HTTP_PROXY var; a non-empty list restricts the subprocess to matching vars only (the pool IPC var is always passed). Set BEFORE App::run().

cgiPoolMaxRequests()  : int

Per-subprocess request count before recycle for cgiMode('pool').

cgiPoolSize()  : int

Worker count for cgiMode('pool') — the native FCGI-style subprocess pool. FPM pm.max_children parity. Default 4. Set BEFORE App::run().

cgiScriptAlias()  : void

Register a ScriptAlias-style executable URL prefix (Apache ScriptAlias parity). Any file served under $urlPrefix is treated as executable, regardless of its extension or whether a per-extension backend exists.

cgiSubprocessAutoload()  : bool

Whether cgi_worker.php (proc-mode subprocess entry) loads Composer's vendor/autoload.php on startup. Default false — restores pre-v0.2.20 behaviour suitable for unmodified WordPress / Drupal / Joomla / plain PHP. Set to true when your public/*.php files explicitly need \ZealPHP\App or framework classes inside the CGI subprocess.

cgiTimeout()  : int

Max seconds to wait for a proc-mode CGI subprocess to emit its metadata line before SIGTERM/SIGKILL. Apache CGIScriptTimeout parity. Default 60.

clearTimer()  : void

Cancel a timer returned by tick() or after().

clientIp()  : string

Resolve the real client IP for the current request, honouring the $trusted_proxies allow-list. Behaviour:

coerceStatusCode()  : int

Coerce a handler's int return value to a valid HTTP status code.

compileMiddlewareChain()  : array<int, MiddlewareInterface>

Resolve a normalized middleware spec (instances + alias strings) to a flat list of MiddlewareInterface instances. Called once per route at App::run() boot time, so the dispatch hot path never does a registry lookup or new.

composeRequestArray()  : array<string, mixed>

Compose $_REQUEST from the GET and POST bags per PHP's default request_order='GP' (#356).

coroutineCwdIsolation()  : bool

Per-coroutine CWD isolation (#323) — see the $coroutine_cwd_isolation docblock. The ext C-level flag is asserted at App::run() boot wiring (alongside the other isolation knobs) so the scheduler hooks are guaranteed installed and the worker baseline is captured pre-fork; setting it here only records the intent.

coroutineGlobalsIsolation()  : bool

Per-coroutine $GLOBALS isolation. See $coroutine_globals_isolation docblock. Requires ext-zealphp 0.3.6+.

coroutineGlobalsMemoryAdvisory()  : void

One-time boot-time advisory for coroutineGlobalsIsolation(true).

coroutineLibxmlIsolation()  : bool

Per-coroutine libxml error-flag isolation — see the $coroutine_libxml_isolation docblock. Asserted at App::run() boot wiring.

coroutineLocaleIsolation()  : bool

Per-coroutine locale isolation — see the $coroutine_locale_isolation docblock. Asserted at App::run() boot wiring (pre-fork, so a boot-time setlocale() becomes the baseline); setting here records the intent.

coroutineMbencIsolation()  : bool

Per-coroutine mb-internal-encoding isolation — see the $coroutine_mbenc_isolation docblock. Asserted at App::run() boot wiring.

coroutineStaticsIsolation()  : bool

Stage 5 per-coroutine function-static isolation. Opt-in — see $coroutine_statics_isolation docblock for the perf tradeoff. The ext C-level flag is asserted at App::run() boot wiring (alongside the other isolation knobs) so the scheduler hooks are guaranteed installed first; setting it here only records the intent.

coroutineTimezoneIsolation()  : bool

Per-coroutine default-timezone isolation — see the $coroutine_tz_isolation docblock. Asserted at App::run() boot wiring.

coroutineUmaskIsolation()  : bool

Per-coroutine umask isolation — see the $coroutine_umask_isolation docblock. Asserted at App::run() boot wiring (pre-fork baseline).

decodeUntilStable()  : string

Percent-decode a path repeatedly until it stops changing.

defaultCharset()  : string

Apache AddDefaultCharset. Server-wide default.

defaultMimeType()  : string

Apache DefaultType / PHP default_mimetype. The Content-Type CharsetMiddleware applies to responses that don't set one. Pass '' to disable. No-arg call returns the current value.

defaultStaticHandlerLocations()  : array<int, string>

The built-in default static_handler_locations — DIRECTORY entries only, every one trailing-slash terminated so OpenSwoole's raw string-prefix match is segment-bounded (a bare /js would steal /json).

defineIsolation()  : bool

Per-request define() isolation. Opt-in — see $define_isolation docblock.

delete()  : void

describeRoutes()  : array{global: list, aliases: list, when: list}>, routes: list, path: string, middleware: list, handler: string}>}

Introspect the routing + middleware topology — the data behind the "middleware visualizer" (think Traefik's dashboard for your own routes).

devReload()  : bool

Enable/disable dev route hot-reload. When on, each worker polls the route/*.php mtimes and calls reloadRoutes() on change — "save file → routes update" with no process restart. A no-arg call returns the resolved value; null (the default) falls back to the ZEALPHP_DEV env var. OFF in production, where the route table stays master-loaded + COW-shared.

directoryIndex()  : array<int, string>

directorySlash()  : bool

Apache DirectorySlash — redirect /foo → /foo/ when foo is a directory.

dispatchTaskCallback()  : array{task: array, result: mixed}|false

Dispatch payload for the $server->on('task', …) callback.

display_errors()  : void

displayErrors()  : bool

Whether framework error pages render the captured exception and stack trace inline. Secure-by-default (#412): a one-arg call sets the value explicitly (and wins forever after); a no-arg call returns the resolved value — when never set explicitly, null falls back to the ZEALPHP_DEV env var, so production (env unset) returns false and never leaks traces.

documentRoot()  : string

Apache DocumentRoot equivalent. Relative path → resolved against cwd; absolute path → used as-is. Drives App::include() resolution and the implicit-route file lookups.

emitEffectiveStatus()  : int

Emit the EFFECTIVE response status and return the code that reached the wire. Resolves the raw header("HTTP/x.x <code> <reason>") override (#327): when the request carries RequestContext::$raw_status_code, that code is emitted — with its verbatim reason when one was given, else the IANA phrase — exactly as Apache mod_php forwards an explicit status line. Without an override this is emitStatus() on the PSR status. Callers use the returned code for body-forbidding rules and access logging so they agree with the wire.

emitGeneratorStream()  : Response

Stream a \Generator response chunk-by-chunk to the live OpenSwoole response (SSR streaming), returning an empty placeholder Response once done. Shared by the route dispatcher (dispatchMatched) and ZealAPI's runHandlerWithContract so both stream identically. HEAD sends headers only (no body). Assumes the caller has already discarded its output buffer.

emitStatus()  : void

Set the response status via OpenSwoole's two-arg form so codes its native list doesn't recognise still emit correctly on the wire.

enableCoroutine()  : bool

OpenSwoole's enable_coroutine server setting — whether each inbound HTTP request is auto-wrapped in its own coroutine. When false, requests run synchronously one at a time per worker (a worker handling request N blocks any other inbound request until N completes). When true, requests can yield on hooked I/O and other requests dispatched on the same worker make progress.

exec()  : array{output: string, code: int, signal: int}

Coroutine-safe command execution.

exitHookAdvisory()  : string|null

Boot-time advisory for App::hookExit(true) set without a coroutine scheduler (#454). The ext-zealphp exit() interception is scheduler-bound: with enableCoroutine off (mixed / in-process-sync modes) a userland exit()/die() still throws OpenSwoole\ExitException (extends \Exception) — which a legacy try { … exit; } catch (\Exception) router swallows — NOT ZealPHP\HaltException. Forcing the hook on there is silently inert, so surface it at boot rather than let the developer believe exit() is protected. Returns the advisory string, or null when N/A; the null (auto) default follows the scheduler and never warns. Testable seam.

fatalGuardRelease()  : void

#338 — release a response tracked by fatalGuardTrack().

fatalGuardTrack()  : int

#338 — track an in-flight raw response; returns the release key.

fatalResponseGuard()  : void

#338 — native shutdown callback (registered in registerAllOverrides() BEFORE the register_shutdown_function override installs). On a fatal, answers every in-flight connection with a minimal 500 — mod_php parity — instead of leaving clients to time out, and surfaces the fatal in the PHP error log (debug.log misses engine fatals; that silence is what made ext-zealphp#36 a multi-day hunt).

fcgiAddress()  : string

FastCGI backend address for App::cgiMode('fcgi') dispatch.

fileETag()  : bool

Apache FileETag. false ⇒ ETagMiddleware emits no ETag and never 304s (FileETag None). No-arg call returns the current value.

formatAccessLogLine()  : string

Render one access-log line for the current request using App::$access_log_format.

fragment()  : void

Declare a named region inside a template — the htmx-essay "template fragment" pattern. The same template renders the full page when called via App::render('page', $args), and just the named region when called via App::render('page', ['fragment' => $name] + $args). One file, two responses — no separate partial file required.

functionIsolation()  : bool

Per-request function/class/include isolation. Opt-in — see $function_isolation docblock.

get()  : void

getCurrentFile()  : string

Returns the current executing script name without extenstion

getErrorHandler()  : array{handler: callable, param_map: array, raw: bool}|null

getFallback()  : array<string, mixed>|null

getServer()  : Server|Server|null

Return the underlying OpenSwoole server. Use this when you need to push to a WebSocket client from a context that didn't receive $server as a callback argument — e.g. from an App::subscribe pub/sub handler, an App::tick timer, or a sidecar process registered via App::addProcess.

globalScopeInclude()  : bool

Stage 8 global-scope request include (coroutine-legacy). A no-arg call returns the current setting; a one-arg call sets it. See the $global_scope_include docblock for the contract. Set BEFORE App::run().

go()  : int|false

Request-aware go() — spawns a child coroutine that INHERITS the current request's context ($g + the live superglobals, #42). Use inside handlers instead of raw go() whenever the child reads $g->server / $_SERVER / $_GET etc. Returns the child's coroutine id, or false if creation failed.

group()  : void

Route group — apply a shared URL prefix and/or a shared middleware chain to many routes at once (Traefik chains, Slim/Laravel route groups).

hookAll()  : int

OpenSwoole\Runtime::enableCoroutine($flags) — process-wide PHP I/O hooks that make blocking calls (fopen, fread, curl, mysqli, etc.) yield to the coroutine scheduler instead of blocking the worker. PDO is intentionally NOT hooked in OpenSwoole 22.1 / 26.2 regardless of this flag — Doctrine queries always block.

hookExec()  : bool|null

Toggle the coroutine-safe exec family hook (backtick / shell_exec / exec / system / passthru). Pass null (or no arg) to read the current value; pass a non-null value to set and return it. null = auto = follow coroutine mode (resolves to self::$superglobals === false) at run() time; overriding these built-ins routes them through coroutine-safe equivalents.

hookExit()  : bool|null

Toggle the ext-zealphp exit()/die() → ZealPHP\HaltException interception (ext#47). Pass null (or no arg) to read; non-null to set.

hostnameLookups()  : bool

Apache HostnameLookups. Default false — blocking DNS is a perf cost.

ignorePhpExt()  : bool

Whether URLs ending in .php are blocked with 403. Default true (Apache RewriteRule \.php$ - [F] parity). Set false to allow direct *.php routing.

include()  : mixed

Run a public/ file with Apache document-root parity and the framework's universal return contract.

includeCheck()  : bool

Checks if the given file path is safe to serve/execute from the document root. Apache ap_directory_walk / resolve_symlink parity:

includeFile()  : mixed

includeIsolation()  : bool

Per-request require_once cache reset. See $include_isolation docblock.

init()  : App

Initializes the application.

instance()  : App|null

isEnotdir()  : bool

ENOTDIR detection for Apache parity (request.c:1244-1250 — "deny rather than assume not found"). When a path component that should be a directory is actually a regular file (e.g. /home.php/extra), Apache returns 403, not 404, deliberately refusing to leak whether the deeper path exists.

isolation()  : string

The single knob that says HOW a request is isolated — folds the (processIsolation × enableCoroutine × hookAll × cgiMode) cross-product into one intention-revealing value. Pure sugar over the existing fluent setters (they all keep working unchanged); accepts the App::ISOLATION_* constant, an Isolation enum case, or a bare string ("no strong").

keepGlobals()  : bool

Keep $GLOBALS across requests within the worker. See $keep_globals docblock for the full semantics + when to use it.

limitRequestFields()  : int

Apache LimitRequestFields.

limitRequestFieldSize()  : int

Apache LimitRequestFieldSize. Maps to OpenSwoole http_header_buffer_size.

limitRequestLine()  : int

Apache LimitRequestLine. Advisory; OpenSwoole's header buffer covers it.

middleware()  : StackHandler|null

The assembled PSR-15 middleware stack (built at boot from App::$middleware_wait_stack by buildMiddlewareStack()).

middlewareAlias()  : void

Register a named, reusable middleware — the "named & shared" middleware vocabulary from Traefik, the route-middleware alias from Laravel.

mode()  : void

High-level mode preset — sets BOTH axes (superglobals + isolation) in one call. Sugar over the fine-grained setters; accepts an App::MODE_* constant or a bare string ("no strong"). All the individual setters remain available to override afterwards.

normalizeMiddlewareSpec()  : array<int, MiddlewareInterface|string>

Validate + flatten a per-route middleware spec into a list, WITHOUT resolving aliases (resolution is deferred to App::run() so an alias may be registered after the route that references it). A single instance or alias string is wrapped into a one-element list.

normalizeRequestPath()  : string

Normalise a request path the way Apache's ap_normalize_path() does (server/util.c): collapse runs of // to a single / (MergeSlashes, on by default), drop /./ segments, and unwind /segment/../ back over the preceding segment. A .. that would climb above root is dropped (clamped at /), matching Apache's behaviour for the routing path.

normalizeUploadedFiles()  : array<string, mixed>

Transpose OpenSwoole's $request->files into PHP/mod_php-canonical $_FILES (issue #304).

nsPathRoute()  : void

nsPathRoute: Define a route under a namespace but allow the last parameter to capture everything (including slashes).

nsRoute()  : void

nsRoute: Define a route under a specific namespace.

offPubSub()  : int

BC alias for unsubscribe(). See onPubSub docblock.

onProcess()  : void

BC alias for addProcess(). The on*-prefixed name was a misnomer (this method REGISTERS a process — it isn't an event). New code should call App::addProcess(); pairs symmetrically with OpenSwoole's $server->addProcess() API.

onPubSub()  : void

BC alias for subscribe(). The original on*-prefixed name was a misnomer — the act IS subscribing, not an event. New code should call App::subscribe() directly; pairs symmetrically with Store::publish().

onReliableMessage()  : void

BC alias for subscribeReliable(). See onPubSub docblock.

onSignal()  : void

Register a signal handler. Fires in the master process by default; pass $workerOnly=true to fire only inside workers.

onWorkerStart()  : void

Register a callback to run inside every worker's workerStart event.

onWorkerStop()  : void

Register a per-worker shutdown hook. Runs inside the worker process when it exits (max_request recycle, graceful shutdown, or reload), BEFORE the process terminates — the reliable place to flush per-worker state (counters, buffered I/O, coverage dumps). Unlike register_shutdown_function, this fires on OpenSwoole's signal-driven worker stop.

opcacheLegacyAdvisory()  : string

Build the opcache + coroutine-legacy boot advisory string. Split out of opcacheLegacyBootCheck() as a pure (opcache-independent) seam so both dups_fix branches are unit-testable without opcache enabled in the SAPI.

opcacheLegacyBootCheck()  : string|null

options()  : void

parallel()  : array<int, T|null>

Fork-join helper — runs every closure in $tasks in its own coroutine in parallel and returns the results in input order.

parallelLimit()  : array<string|int, mixed>

Bounded fan-out — runs $fn over each item with at most $concurrency in-flight coroutines at a time. Results keyed by the input's original keys.

parseCgiResponse()  : array{status: int|null, headers: list, body: string}

Parse a raw CGI/1.1 interpreter response (RFC 3875) into status, headers and body — pure, side-effect-free string handling.

parseCookieHeader()  : array<string, mixed>

Parse a raw Cookie: header through PHP's cookie treat-data semantics (issue #305) — the same php_default_treat_data routine PHP applies to the query string, but with the cookie value-decoding rule:

parseCss()  : array<string, array<string, string>>

Parses the given CSS file.

patch()  : void

pathInfo()  : bool

Apache PATH_INFO — expose the path suffix after a script name as PATH_INFO in $_SERVER (e.g. /script.php/extra/path → PATH_INFO=/extra/path).

pathWithinRoot()  : bool

Boundary-aware containment test: is $candidate the same path as $root, or a descendant of it?

patternRoute()  : void

patternRoute: Allow full control of the pattern without {param} placeholders.

perRequestStateResetsActive()  : bool

True when the per-request state RESETS — zealphp_reset_request_rtcaches() / zealphp_reset_request_statics() / zealphp_reset_request_class_statics(), run in the session-manager finally block — are SAFE to execute.

post()  : void

poweredByHeader()  : string|null

Resolve the X-Powered-By header value for the current ServerTokens setting, or null when the header should be omitted. Consumed at the response-emission boundary; exposed for introspection/testing.

preloadClasses()  : void

Register classes to compile at worker start so they are never cold- autoloaded under request concurrency (coroutine-legacy mode). Call BEFORE App::run(). Idempotent; duplicates are harmless. See App::$preload_classes for the full rationale and the failure mode it prevents.

preloadClassmap()  : void

Opt into warming the ENTIRE Composer classmap at worker start — the structural fix so a user app's own classes (autoloaded on demand inside handlers) are born LINKED, never compiled on the concurrent cold path.

preloadDir()  : void

Register a source directory to warm at worker start: every class / interface / trait / enum declared under $dir (recursively) is autoloaded+linked single-coroutine before request concurrency. Use this for PSR-4 apps WITHOUT an optimized classmap, or any app whose own autoloader (not Composer's classmap) resolves these symbols. Call BEFORE App::run(). The symbol must still be resolvable by a registered autoloader — a pure require_once legacy app (no autoloader) won't warm this way; run such apps in legacy-cgi mode (no coroutine race) instead.

prependToStreamable()  : Generator

Combine a pre-yield buffered chunk with a Generator so the wire order is "echo first, then stream". Returns a new Generator that yields the buffered chunk before delegating to the original.

processIsolation()  : bool

Per-include CGI process isolation (Apache mod_php-style fresh process per file). When true (the default in superglobals mode), App::include() dispatches each .php file through cgi_worker.php via proc_open() — global state (defined classes, constants, ini_set, output handlers) is contained inside the subprocess. When false, runs in-process via executeFile() — saves the ~30-50ms proc_open + PHP startup + autoloader cost per call, but every include shares the worker's PHP arena.

publish()  : int

Fire-and-forget Redis pub/sub publish.

publishReliable()  : string

Reliable publish via Redis Streams (XADD) — at-least-once delivery via consumer groups. Returns the Redis-generated message id.

put()  : void

rawExec()  : string|null

Raw blocking command execution via proc_open.

reasonPhrase()  : string

Look up an IANA reason phrase for the given status code. Used by emitStatus() to pass an explicit reason to OpenSwoole's two-arg $response->status($code, $reason) — required because the native one-arg form silently rejects codes missing from its internal C list (notably 451, even on ext 26.x), and the request emits HTTP 200 instead.

reassertRotatedSessionId()  : array<string, mixed>

Re-assert a session id the session manager already rotated, over a freshly-parsed request-cookie map (#371, CWE-384 session fixation).

rebindRequestInput()  : void

Re-establish the request-input superglobals ($_GET / $_POST / $_COOKIE / $_SERVER / $_FILES / $_REQUEST) FROM the per-coroutine OpenSwoole request, in the coroutine that is about to read them. Called right before every handler / included-file dispatch in coroutine-legacy mode.

refreshGlobalsBaseline()  : bool

Re-capture the per-coroutine $GLOBALS baseline from the current symbol table.

registerCgiBackend()  : void

Register a per-extension CGI backend. Apache AddHandler/ProxyPassMatch + nginx fastcgi_pass-per-location parity.

reloadRoutes()  : int

**Hot-reload the route table from route/*.php WITHOUT restarting the worker process.** Restores the app.php-defined baseline (explicit routes + the alias / App::when registries), re-includes the route files (picking up edits — opcache is invalidated for them first), re-appends the framework's implicit routes in priority order, and rebuilds the dispatch table. Returns the new route count.

render()  : mixed

Render a template with the provided data.

renderError()  : ResponseInterface

Render the response for an error status. Dispatches a user-registered handler if one exists (status-specific takes precedence over catch-all); otherwise returns the framework's default body (HTML or JSON per Accept).

renderHtmx()  : mixed

htmx-aware render: return a fragment (partial) for an htmx request, the full page otherwise — a thin selector over {@see App::render()} that keeps the universal return contract and streaming intact (it does NOT touch executeFile(); it only chooses what to render).

renderStream()  : Generator

Render a template as a Generator. Streaming templates (return-a-Closure or return-a-Generator) yield directly; echo-style templates yield their buffered output once.

renderToString()  : string

Render a template and return the result as a string. Generators are consumed; Closures are invoked with param injection; arrays/objects are JSON-encoded.

requestCookieMap()  : array<string, mixed>

mod_php-canonical cookie map for a request (issue #305).

requestIsHttps()  : bool

Whether the request arrived over HTTPS. X-Forwarded-Proto is honoured ONLY when the immediate peer (REMOTE_ADDR) is a configured trusted proxy — parity with App::clientIp(). Public so the session layer (zeal_session_start's Secure-cookie auto-detect) shares this one gated source of truth instead of trusting the header from any client.

resetCgiBackends()  : void

Reset the CGI backend + ScriptAlias registries. Test-support helper — lets unit tests start from a clean registry without process recycling.

resolveActiveSessionHandler()  : SessionHandlerInterface|null

Resolve the configured session handler instance — the single source of truth the zeal_session_* overrides and both session managers consult.

resolveCgiBackend()  : array{backend: array{mode: string, interpreter?: string|null, address?: string, fcgi_params?: array, exec_paths?: array}, mayExecute: bool}

Resolve the CGI backend config + execution permission for a given path.

resolveCgiEnv()  : void

Resolve the CGI subprocess-pool config from the environment at boot.

resolveDocumentRoot()  : string

Resolve App::$document_root to an absolute path. Relative values are treated as ${App::$cwd}/$document_root; absolute values pass through.

resolveMaxRequest()  : int

Resolve OpenSwoole's max_request from the raw ZEALPHP_MAX_REQUEST env value. #449 — getenv() returns false when unset and the string "0" when explicitly set to disable; the old getenv() ?: 100000 collapsed both to the default ("0" is falsy in ?:), so ZEALPHP_MAX_REQUEST=0 ("set 0 to disable", per docs/deployment.md) silently never reached the server. Test for presence (=== false) instead, so 0 is honoured (OpenSwoole: never recycle the worker).

resolveWhenMiddleware()  : array<int, MiddlewareInterface>

Select the App::when middleware chain for a normalized request path — every matching scope's instances flattened in registration order (outermost first). Memoized per path; the registry is immutable after boot, so this never recomputes for a repeated path. Returns [] (the fast path) when nothing is registered or nothing matches.

route()  : void

Registers a route with the application.

routes()  : array<int, MiddlewareInterface|string>, backend?: array{mode: string, interpreter?: string, address?: string, fcgi_params?: array}|null}>

routesByExactMethod()  : array<string, array<string, MiddlewareInterface|string>, backend?: array{mode: string, interpreter?: string, address?: string, fcgi_params?: array}|null}>>

routesByMethod()  : array<string, array<int, MiddlewareInterface|string>, backend?: array{mode: string, interpreter?: string, address?: string, fcgi_params?: array}|null}>>

run()  : void

runRequestStaticsBeginRefresh()  : bool

Request-BEGIN function-static refresh (coroutine-legacy, #28).

sapiName()  : string|null

mod_php-parity SAPI name reported by the php_sapi_name() override.

serveDirectory()  : mixed

Apache DirectorySlash + DirectoryIndex behavior.

serverAdmin()  : string|null

Apache ServerAdmin. Contact email/identifier embedded in the framework's default error pages. Pass null (or '') to clear.

serverTokens()  : string

Apache ServerTokens. Controls the X-Powered-By header detail.

sessionDataSize()  : int

Max serialized session size in bytes for TableSessionHandler.

sessionHandler()  : string|SessionHandlerInterface|null

Session storage backend selector. See $session_handler docblock.

sessionLifecycle()  : bool

Toggle ZealPHP's per-request session lifecycle. When disabled, the SessionManager / CoSessionManager OnRequest wrapper skips session_start / cookie emission / session write-close — request-context init (openswoole_request, zealphp_response, error-stack reset) still runs unconditionally. Use this when another framework (e.g. Symfony's NativeSessionStorage via the zealphp-symfony bridge) owns sessions and you don't want ZealPHP racing it for the PHPSESSID cookie. The zeal_session_* uopz overrides remain installed and callable from user code either way.

sessionMaxRows()  : int

Max concurrent sessions in TableSessionHandler's OpenSwoole\Table.

sessionSavePath()  : string

File-backing directory for session storage. Default /var/lib/php/sessions.

sessionStrictMode()  : bool

PHP session.use_strict_mode parity (#244). When on (the default), a client-supplied session id that loads an empty session is rotated to a fresh server-generated id, defeating session fixation. Pass false to accept client-supplied ids verbatim (only safe for multi-node setups without shared/sticky session storage — see App::$session_strict_mode).

sessionTtl()  : int

Session TTL in seconds. Default 1440 (PHP's default). See $session_ttl.

setErrorHandler()  : void

Register a custom error page handler — Apache's ErrorDocument equivalent.

setFallback()  : void

Register a fallback handler for unmatched routes (like Apache's RewriteRule . /index.php [L]).

silentRedeclare()  : bool

Stage 3 silent-redeclare. Opt-in — see $silent_redeclare docblock.

staticHandlerLocations()  : array<int, string>

URL-prefix whitelist for static-file serving. Empty array (default) allows any path under document_root. When non-empty, only paths whose prefix matches one of the listed strings are served as static files; others fall through to route matching. No-arg call returns the current list.

stats()  : array<string, mixed>

Aggregated framework health snapshot — backends, pool, workers, memory, uptime, plus per-subsystem counters (X-4). Designed for /healthz middleware exposure + Prometheus exposition (see App::onSchedule v0.3.0 P1.10 plan).

statusForbidsBody()  : bool

Whether a status code MUST be sent without a message body (RFC 7230 §3.3.2 / RFC 9110 §6.4.1): every 1xx informational response, plus 204 No Content and 304 Not Modified. For these, a server must emit neither a body nor a Content-Length / Content-Type header — a non-empty body is a framing violation that some clients treat as the start of the next response. The emit chokepoint uses this to drop any body a handler accidentally produced (#290).

stripTrailingSlash()  : bool

Apache RewriteCond %{REQUEST_FILENAME} !-d; RewriteRule ^(.+)/$ /$1 [R=301,L].

subscribe()  : void

Register a Redis pub/sub handler — runs once for every message App::publish (or any other Redis client) sends on the channel.

subscribeReliable()  : void

Register a Redis Streams consumer-group handler. At-least-once delivery via XREADGROUP. Handler signature: function(string $payload, string $messageId, string $stream, array $fields): bool Return true to XACK (message removed from pending). Return false OR throw to leave pending (retried on consumer recovery).

superglobals()  : void

Toggle the superglobals-mode lifecycle. See App::$superglobals for the full semantics. Must be called BEFORE App::run() — the method calls refuseAfterRun() and throws \RuntimeException if the server is already serving requests.

synthesizeRequestServerVars()  : array<string, bool|float|int|string|null>

Synthesize the mod_php request-surface $_SERVER vars that OpenSwoole's raw $request->server omits or gets wrong (issue #306 + #307). Pure transform of an already-built server array — operates on the upper-cased keys buildServerVars() produces, so it is unit-testable in isolation:

tick()  : int

Recurring timer: calls $fn every $ms milliseconds in this worker.

traceEnabled()  : bool

Apache TraceEnable. Default OFF for security (XST attack vector).

trustedProxies()  : array<int, string>

Trusted proxy CIDRs consulted by App::clientIp().

tryInclude()  : mixed

Like App::include() but returns null instead of 403 when the requested file does not exist under the document root. Use for "try this file, fall through to something else if missing" patterns:

unsubscribe()  : int

Unregister handlers for a channel/pattern. With $handler null, removes every registered handler for that channel. Returns the count removed.

useCanonicalName()  : bool

Apache UseCanonicalName. See $use_canonical_name docblock.

usernameProvider()  : callable|null

Register a callback that ZealAPI::getUsername() consults.

when()  : void

Scope a middleware chain to a URL **path** — the centralized, "think like Traefik" way to apply middleware to a slice of the site, **including the ZealAPI layer**. Because every request (route or api/** file) flows through the same stack and api/admin/x is just the URL /api/admin/x, one mechanism covers everything — there is no separate "api middleware".

ws()  : void

Register a WebSocket endpoint. Returns void — the OpenSwoole WebSocket\Server is owned by the framework lifecycle, not the route registration. To push to a client you have **two** ways to reach the server object:

wsRoutes()  : array<string, array{message: callable, open: callable|null, close: callable|null}>

isExactRoutePath()  : bool

__clone()  : mixed

__construct()  : mixed

Private constructor — use App::init() to obtain the singleton instance.

activateIsolationRuntime()  : void

Activate the ext-zealphp per-coroutine isolation runtime stack (superglobals / define / $GLOBALS / silent-redeclare / function-static / include isolation) and register the matching onWorkerStart hooks.

applyRouteBackend()  : array{backend: array{mode: string, interpreter?: string|null, address?: string, fcgi_params?: array, exec_paths?: array}, mayExecute: bool}

Apply the per-request route backend override (set by the matched route's backend: option in ResponseMiddleware::dispatchRoute()) over a resolveCgiBackend() result. A route that names a backend is itself the ExecCGI authorisation for its App::include(), so mayExecute is forced true. No override → the resolved backend passes through unchanged.

assertUrlPrefix()  : void

Validate that an ExecCGI scope value is a URL path prefix, not a filesystem path. exec_paths / cgiScriptAlias prefixes are matched against the request URL (resolveCgiBackend() → pathUnderPrefix()), so a filesystem path (e.g. '/var/www/cgi-bin') can never match the incoming URL and silently yields a bare 403 (GitHub #155). Fail fast at registration instead: reject anything that is not absolute (/-rooted) or that resolves to an existing directory on disk. A real URL prefix like '/cgi-bin' is not a directory on a normal host, so correct configs pass untouched.

backendKind()  : string

baseServerVars()  : array<string, string>

The static CGI/SAPI server vars mod_php exposes even OUTSIDE a request (PHP_SELF, SCRIPT_NAME, SCRIPT_FILENAME, REQUEST_URI, DOCUMENT_ROOT).

buildMiddlewareStack()  : void

Reverse + add the queued middleware-wait-stack onto the live PSR-15 StackHandler. Extracted verbatim from App::run() (Phase 3) — runs at the same point, mutating self::$middleware_stack in the same first-registered- outermost order.

buildParamMap()  : array<int, array{name: string, has_default: bool, default: mixed}>

buildServerVars()  : array<string, bool|float|int|string|null>

Build the per-request $_SERVER array from an OpenSwoole request — mod_php parity. Merges $request->server (upper-cased keys), the HTTP_* header vars, and the constant CGI keys mod_php always provides (GATEWAY_INTERFACE, REQUEST_SCHEME, SCRIPT_FILENAME, SERVER_SOFTWARE, …).

cidrContains()  : bool

clearHandlerHeaders()  : void

Clear previously-accumulated response headers from a handler that then failed, keeping only the headers that Apache preserves across an error response (ap_send_error_response: apr_table_clear(r->headers_out) then re-instate headers required by HTTP protocol for specific status codes).

coerceToStream()  : Generator

Coerce an executeFile() result to a Generator. Strings/scalars yield once; Generators yield-from; null yields nothing.

coerceToString()  : string

Coerce an executeFile() result to a string. Generators are consumed and concatenated; arrays/objects are JSON-encoded; null becomes ''.

collapseMappedIp()  : string

Collapse an IPv4-mapped IPv6 address (::ffff:a.b.c.d) to its IPv4 form so an IPv4 CIDR matches a mapped peer (#433). Mirrors IpAccessMiddleware::normalizeIp byte-for-byte. Non-mapped input is returned unchanged.

compileAccessLogFormat()  : array<int, array{kind: string, arg?: string}>

Compile an Apache LogFormat string into a flat token list. Supported directive families (Apache mod_log_config subset): %h %l %u %t %r %s %>s %b %B %D %T %m %U %q %H %v %{NAME}i %{NAME}o %{NAME}e Unknown directives are passed through verbatim (Apache compatibility: mod_log_config logs '-' for unknown but compatibility matters less than surfacing typos to the operator).

compileRouteTable()  : void

Resolve per-route + App::when middleware specs (alias → instance) and (re)build the method-indexed dispatch table. Idempotent — it resets the indexes first, so reloadRoutes() can call it to rebuild from scratch; at boot it runs exactly once.

defaultErrorResponse()  : ResponseInterface

Default error body. Honors Accept: application/json for JSON envelope, otherwise emits HTML. Stack trace included only when App::$display_errors.

executeFile()  : mixed

Run a PHP file with the framework's universal return contract.

fileEntryIsSingle()  : bool

True when $entry is a single PHP file struct (has a scalar/array tmp_name AND error directly on it), rather than an index/name-keyed group of nested file structs.

getFragmentState()  : array{wanted: string, matched: bool, result: mixed}|null

Read and narrow the current fragment-extraction state from $g->memo.

globalScopeIncludeEffective()  : bool

Whether THIS request's App::include() should run at true global scope: the gate is on AND we're in coroutine-legacy (so the per-coroutine globals isolation stack is active). The ext-capability check (function_exists) is done inline at the executeFile() call site. Policy-only helper.

handlerDisplayName()  : string

Human-readable label for a route handler — Class::method for an array callable, otherwise Closure/function.

includeRouteFiles()  : void

Include the route/*.php files (the file-based route definitions).

installCoroutineAutoloadSerializer()  : void

Coroutine-aware autoload serializer — the HAZARD-2 correctness fix for coroutine-legacy mode.

invokeFallbackOrNotFound()  : ResponseInterface

lifecycleBackendMessage()  : string

The error shown when a route backend: (or a cgiBackendAlias) is given a process-wide lifecycle mode instead of a CGI dispatch strategy.

logExecScopeMiss()  : void

Emit a diagnostic when a request matched a registered CGI extension but fell outside its exec_paths scope (ExecCGI off → bare 403). Without this, a misconfigured exec_paths (e.g. a filesystem path that can never match the URL — GitHub #155) surfaces only as an opaque 403. Logs only for files whose extension HAS a registered backend, so unrelated unregistered-extension 403s stay quiet.

middlewareDisplayName()  : string

Human-readable label for a middleware spec entry — the class short-name for an instance, the alias string (verbatim) for an unresolved reference.

normalizeBackendConfig()  : array{mode: string, interpreter?: string, address?: string, fcgi_params?: array}

Normalise + validate one inline backend config array into the canonical shape (mode + the optional interpreter/address/fcgi_params). The single validation point for cgiBackendAlias() and resolveBackendSpec().

normalizeMethods()  : array<int, string>

Normalize a methods array (any shape) into a list of uppercase strings.

normalizeSingleFileEntry()  : array<string, mixed>

Normalise one flat OpenSwoole file struct to PHP canonical shape, adding the PHP 8.1+ full_path key when absent (value = name).

overrideBuiltin()  : void

Install a uopz or ext-zealphp override for a named PHP built-in function, routing calls to the given ZealPHP replacement. Uses zealphp_override() when ext-zealphp is loaded (preferred), falling back to uopz_set_return().

pathUnderPrefix()  : bool

Boundary-safe URL-prefix test. $url is "under" $prefix only when it equals the prefix exactly or begins with $prefix . '/' — so /cgi-bins does NOT match the /cgi-bin scope.

peerInTrustedProxies()  : bool

Match $ip against every entry in App::$trusted_proxies. Wrapper so the CIDR walk lives in one place; callers pass user-controlled input here so the per-entry guard inside cidrContains() is the only validation needed.

phpredisSubscribeWouldBlock()  : bool

H7 detection: would a phpredis SUBSCRIBE/PSUBSCRIBE block the whole worker?

preloadRequestPathClasses()  : void

Warm the per-request framework classes at worker start so the first concurrent request wave never autoloads them under coroutine overlap.

refuseAfterRun()  : void

Throw if a lifecycle setter is being called after App::run() has started. The Session-manager class, OpenSwoole's enable_coroutine flag, and HOOK_ALL are all frozen at boot — mid-game mutation of $superglobals etc. leaves the framework in a partial state that races on $_GET/$_POST/$_SESSION. Boot-only is the contract.

registerAllOverrides()  : void

Install all ZealPHP uopz/ext-zealphp built-in overrides in one shot.

registerImplicitRoutes()  : void

Register the implicit framework routes (api dispatch, .php-ext block, dotfile block, index, CGI extension/ScriptAlias URL parity, and the public file/directory catch-alls).

registerOnRequest()  : void

Register the OnRequest event handler — the per-request entry point that populates RequestContext, runs the middleware stack, fires shutdown functions, and emits the response. Extracted verbatim from App::run() (Phase 3) — runs at the same point; the only captured locals are $server and the resolved session-manager class name.

registerSessionGc()  : void

Schedule the deterministic session garbage collector on a worker-0 timer.

registerTaskHandlers()  : void

Register the task + finish OpenSwoole event handlers when task workers are configured. Extracted verbatim from App::run() (Phase 3) — runs at the same point, gated on the same effective_settings['task_worker_num'].

registerWebSocketHandlers()  : void

Register the WebSocket open/message/close/shutdown event handlers, sharing the per-worker fd → ws-path map across the closures. Extracted verbatim from App::run() (Phase 3); the $wsFdMap is local to these four closures.

registerWorkerStart()  : void

Register the workerStart event handler — re-registers the php:// stream wrapper, fires user onWorkerStart hooks, and wires dev route hot-reload.

registerWorkerStop()  : void

Register the workerStop event handler — fires user onWorkerStop hooks then logs worker-recycle observability. Extracted verbatim from App::run() (Phase 3).

renderAccessLogToken()  : string

Render one compiled access-log token. Kept separate from the tokenizer so the hot path (per-request) only does the table-lookup half; the tokenize path runs once per format-string change.

resolveBackendSpec()  : array{mode: string, interpreter?: string, address?: string, fcgi_params?: array}|null

Resolve a route backend: spec — a bare mode string, a registered alias name, or an inline config array — into a concrete backend config. null passes through (no backend). Called at route registration; the dispatch hot path never re-resolves.

resolveClosureParams()  : array<int, mixed>

Resolve a Closure's parameters by name from $args, using each parameter's default value when the name is absent. Reflection is cached per file path so repeated calls (e.g. streaming templates yielded in a loop) pay only one reflection cost per worker.

resolveMiddleware()  : MiddlewareInterface

Resolve one spec entry to an instance. An instance passes through; an alias string is looked up in the registry (name or name:arg1,arg2).

resolveTemplatePath()  : string

Resolve a template-file name to an absolute path.

restoreFragmentState()  : void

Restore $g->memo['_fragment'] to its prior state. Called by executeFile() to undo fragment-mode setup for nested renders and on error paths. null means "no fragment mode was active before" — drop the slot entirely so the next App::fragment() call falls into the normal inline-render branch.

routeBackendSpec()  : array{mode: string, interpreter?: string, address?: string, fcgi_params?: array}|null

Combine the two ways a route can declare a backend — the 'backend' key in $options and the backend: named argument — and resolve to a concrete config. The named argument wins when both are present. Returns null (the fast path: no per-route backend) when neither is set.

routeFileWithTopLevelFunction()  : string|null

The first route/*.php file that declares a top-level function (which cannot be re-included without a redeclaration fatal), or null if every route file is function-free and therefore hot-reloadable. The path is cwd-relative for logging. A $x = function(){} closure has no name and is not matched; a class method carrying a visibility keyword isn't either.

routeMiddlewareSpec()  : array<int, MiddlewareInterface|string>

Combine the two ways a route can declare middleware — the 'middleware' key of the $options array and the middleware: named argument — into a single normalized spec. When both are present the array-option entries run first (outermost). Stored on the route as the raw spec; resolved to instances at App::run().

runTasksSequentially()  : array<int, T>

Sequential fallback for parallel() when no coroutine scheduler is available (reactor worker in mixed / legacy-cgi — #429). Runs each task in input order; the first throw propagates immediately, matching parallel()'s fail-fast-on-first-error contract.

runUserFile()  : mixed

Run a user file (template / public page) in an ISOLATED scope and return its value (#458). The file is included HERE, not in executeFile(), so a page that reuses a common variable name — $g, $result, $output, $args, … — only shadows this helper's throwaway locals and never corrupts executeFile()'s framework state used after the include (which previously fatalled "Attempt to assign property _ob_floor on array" → 500 when a page did $g = …). Locals are $__zeal_-prefixed (and EXTR_SKIP keeps them safe during extract) to stay clear of app/template names.

safeStats()  : array<string, mixed>

serverNameFromHost()  : string

Derive SERVER_NAME from the request Host header. SERVER_NAME is the server host NAME only (CGI/1.1, RFC 3875 §4.1.14) — the port belongs in SERVER_PORT. The Host header carries host[:port], so strip the port.

symbolDefined()  : bool

True if $name is already defined as a class, interface, or trait (autoload disabled). Extracted so the autoload serializer can re-test "is it loaded now?" after a concurrent load.

symbolsInFile()  : array<int, string>

Extract fully-qualified class/interface/trait/enum names declared in a PHP file via the tokenizer — without executing it. Single namespace per file is the common case; multiple namespaces are handled.

transposeFileGroup()  : array<string, array<string|int, mixed>>

Transpose an index-major group of file structs (the OpenSwoole shape for files[] / doc[main]) into PHP's field-major layout. Recurses through nested name groups so ['main' => <struct>, 'thumb' => <struct>] yields ['name'=>['main'=>…,'thumb'=>…], 'tmp_name'=>[…], …].

validateLifecycleCombination()  : void

Validate lifecycle mode combinations at boot.

warmBulkPreloads()  : void

Bulk warming (whole Composer classmap + registered directory trees) — runs in the MASTER process before $server->start(), NOT in a worker coroutine. This is load-bearing: warming hundreds/thousands of arbitrary classes inside the coroutine onWorkerStart is unsafe — a class with load-time I/O (or anything the runtime hooks coroutinize) YIELDS, and the worker then accepts requests MID-WARMUP → cold concurrent compile → the duplicate-CE / unlinked race we are trying to avoid (empirically: a classmap warm in onWorkerStart reintroduced HAZARD-2 TypeErrors). The master has no coroutine scheduler, so every load is blocking + atomic; the warmed (linked) classes are then COW-forked into every worker. Same model as PHP's opcache.preload. No-op unless preloadClassmap()/preloadDir() registered something.

warmClass()  : void

Trigger one symbol's autoload+link, swallowing load errors (a class with an unmet dependency must not abort worker start). class_exists() fires the registered autoloader for classes/interfaces/traits/enums alike.

warmComposerClassmap()  : void

Warm every class Composer's registered loaders know about. Iterates the classmap of each registered Composer\Autoload\ClassLoader and triggers its autoload (single-coroutine at worker start → whole hierarchy linked).

warmDir()  : void

Warm every PHP-declared symbol under a directory tree. Reads each .php file and extracts its namespace + class|interface|trait|enum names via the tokenizer (no file is executed), then triggers each symbol's autoload.

whenScopeMatches()  : bool

Whether an App::when scope matches a normalized path. Prefixes match on segment boundaries (the trailing / stops /admin matching /administrators); '/' matches all; regex scopes use preg_match.

wireProcessHandlers()  : void

Internal: wire registered sidecar processes into the OpenSwoole server via $server->addProcess(). Called from App::run() after the server is constructed but before start().

wirePubSubBoot()  : void

One-time hook into onWorkerStart that builds + starts the RedisPubSub and RedisStreams runners based on what's in the registries. Re-callable; only wires once.

App::addProcess('log-shipper', function (\OpenSwoole\Process $p): void {
    while ($line = fgets(STDIN)) {
        shipToS3($line);
    }
}, workers: 1, coroutine: true);

App::authChecker(fn() => !empty($_SESSION['user_id']));
App::authChecker(fn() => MyAuth::status() === MyAuth::LOGGED_IN);

App::cgiBackendAlias('wp-fork', 'fork');                         // bare mode
App::cgiBackendAlias('py', ['mode' => 'proc', 'interpreter' => '/usr/bin/python3']);
App::cgiBackendAlias('fpm', ['mode' => 'fcgi', 'address' => 'unix:/run/php-fpm.sock']);

// template/contacts/list.php
<ul>
  <?php foreach ($contacts as $contact): ?>
    <?php App::fragment("contact-{$contact->id}", function() use ($contact) { ?>
      <li id="contact-<?= $contact->id ?>"><?= htmlspecialchars($contact->name) ?></li>
    <?php }); ?>
  <?php endforeach; ?>
</ul>

$server = App::getServer();
if ($server instanceof \OpenSwoole\WebSocket\Server && $server->isEstablished($fd)) {
    $server->push($fd, $payload);
}

$app->group('/admin', ['auth', 'admin-only'], function ($g) {
    $g->route('/users',    fn() => User::all());
    $g->route('/settings', fn() => Settings::get());
});