Alpha ZealPHP is early-stage and under active development. APIs may change between minor versions until v1.0. Feedback and bug reports welcome on GitHub.
Esc
API Index — Namespaces, Packages, Reports, Indices

ZealPHP

Table of Contents

Namespaces

Cache
Diagnostics
Docs
HTTP
Input
Learn
Legacy
Log
Middleware
Session

Classes

App
ResponseMiddleware
TemplateUnavailableException
LocationHeaderMiddleware
Cache
Cache — Tiered key-value cache (memory + file)
Counter
Counter — OpenSwoole\Atomic adapter
GithubStars
GitHub stargazer-count cache.
HaltException
Thrown to cleanly halt page execution without killing the worker process.
IOStreamWrapper
RequestContext
Per-request state container. Lives on Coroutine::getContext() in coroutine mode (recommended default) so each request gets isolated state freed automatically when the coroutine ends. In legacy superglobals mode it's a process-wide singleton bridging declared properties to PHP's $_GET / $_POST / $_SESSION etc.
REST
Store
Store — OpenSwoole\Table adapter
StringUtils
ZealAPI
File-based API dispatcher.

Functions

get()  : mixed
env_flag()  : bool
bench_mode_enabled()  : bool
site_url()  : string
site_host()  : string
async_logging_enabled()  : bool
resolve_log_dir()  : string|null
debug_logging_enabled()  : bool
access_logging_enabled()  : bool
log_file_for()  : string|null
log_sink_for()  : Channel|null
log_write()  : void
coprocess()  : mixed
Run a closure in a throwaway child process that HAS the coroutine scheduler, even though the caller does not. This is the escape hatch for parallel I/O from a coroutine-scheduler-OFF worker — i.e. superglobals(true) / enableCoroutine(false) mode (the Symfony/FPM-style lifecycle, where running coroutines in the main worker would race process-wide $_GET/$_POST/$_SESSION and shared framework singletons).
coproc()  : mixed
Thin alias for {@see coprocess()} — same fork-a-coroutine-child semantics, so it shares coprocess()'s untestability (forks a child process; only valid in the superglobals(true)+enableCoroutine(false) mode the coverage gate excludes).
jTraceEx()  : string
jTraceEx() - provide a Java style exception trace
zapi()  : string
elog()  : void
Logs a message with an optional tag and limit.
zlog()  : void
Logs a message with an optional tag and filter.
get_config()  : mixed
get_current_render_time()  : float
Get the current render time since request received and started processing.
indent()  : string
Indend the given text with the given number of spaces
purify_array()  : array<int|string, mixed>
Takes an iterator or object, and converts it into an Array.
uniqidReal()  : string
Generates a unique identifier of a specified length.
access_log()  : void
Logs access details with the given status and length.
response_add_header()  : void
response_set_status()  : void
Sets the HTTP response status code.
response_headers_list()  : array<int, array{0: string, 1: string}>
Retrieves all the response headers.
setcookie()  : bool
setrawcookie()  : bool
header()  : false|void
http_response_code()  : int|null
headers_list()  : array<int, string>
Retrieves all HTTP headers sent by the server.
headers_sent()  : bool
Checks if headers have already been sent and optionally returns the file and line number where the output started.
header_remove()  : void
Remove a previously set response header. With no argument, clears all.
flush()  : void
Force the current output buffer to the client. In main-worker mode, this switches the response into streaming mode (headers flushed, body chunks written via OpenSwoole). Subsequent echo+flush calls stream incrementally.
ob_flush()  : void
ob_end_flush()  : void
ob_implicit_flush()  : void
phpinfo()  : bool
mod_php-parity phpinfo(): render a self-contained HTML document instead of the CLI SAPI's plain-text dump. Matches the native signature — echoes output and returns true. Wired via uopz in App::__construct(); the renderer lives in \ZealPHP\Diagnostics\PhpInfo.
php_sapi_name()  : string
mod_php-parity php_sapi_name(): under the CLI SAPI this natively returns "cli", which legacy apps branch on to disable web-only behavior. When an app opts in via App::sapiName('apache2handler') (or 'fpm-fcgi'), this returns the configured value so such code takes its web path. Default (App::$sapi_name === null) returns the real PHP_SAPI — zero behavior change unless explicitly configured.
filter_input()  : mixed
mod_php-parity filter_input(): native filter_input() reads PHP's internal SAPI request tables, which OpenSwoole never populates (so it returns null under CLI).
filter_input_array()  : array<string, mixed>
mod_php-parity filter_input_array(): the array counterpart of filter_input().
header_register_callback()  : bool
mod_php-parity header_register_callback(): native PHP fires the callback when the SAPI is about to send headers — which never happens the normal way under OpenSwoole. ZealPHP stores it per-request (coroutine-safe, in $g->memo) and invokes it once just before the buffered response headers are flushed, so header() calls inside the callback still land. Last registration wins (matches native, which keeps a single callback). Returns false if there's no request context (e.g. called outside a request).
error_log()  : bool
mod_php-parity error_log(): under the CLI SAPI native error_log() writes to stderr / the php.ini error_log path. ZealPHP routes message_type 0 (system logger) and 4 (SAPI logger) into the framework's async log (debug.log, or stderr if logging is disabled) so legacy error_log() calls land where the rest of the app's diagnostics go — the "we have elog for error_log" contract.
apache_request_headers()  : array<string, string>
Apache mod_php getallheaders() / apache_request_headers() — return all inbound request headers with canonical (Hyphen-Capitalized) case.
getallheaders()  : array<string, string>
apache_response_headers()  : array<string, string>
Apache mod_php apache_response_headers() — currently set outbound headers.
apache_setenv()  : bool
Apache mod_php per-request env table. Backed by Legacy\ApacheContext on G; lifetime = one request. Lazy — only allocated if legacy code calls apache_setenv/getenv/note.
apache_getenv()  : string|false
apache_note()  : string
Apache mod_php apache_note() — per-request note table. Returns previous value.
virtual()  : bool
Apache mod_php virtual() — performs an internal subrequest. Not supported in ZealPHP's single-process model; we log once and return false rather than crashing legacy code.
set_time_limit()  : bool
set_time_limit() — OpenSwoole has its own coroutine/worker timeouts and native PHP execution-time limit is irrelevant here. Treated as no-op success.
ignore_user_abort()  : int
connection_status()  : int
connection_aborted()  : int
output_add_rewrite_var()  : bool
Apache's URL-rewrite output handler — not used in ZealPHP. No-op.
output_reset_rewrite_vars()  : bool
is_uploaded_file()  : bool
is_uploaded_file() — verifies that $filename is one of the temp paths registered in this request's $_FILES. Rejects forged paths from user input.
move_uploaded_file()  : bool
move_uploaded_file() — equivalent of Apache+mod_php behavior, gated by is_uploaded_file() and falling back to copy+unlink across filesystems.
set_error_handler()  : callable|null
Per-coroutine set_error_handler override. The native PHP handler is installed at boot and delegates to G's per-coroutine stack — this override just records the user-space registration without touching the engine.
restore_error_handler()  : bool
set_exception_handler()  : callable|null
restore_exception_handler()  : bool
register_shutdown_function()  : void
Per-request shutdown function — fires after the route handler returns and before the PSR response is emitted, so the function can still call echo/header/http_response_code and have those land in the response.
error_reporting()  : int
Per-coroutine error_reporting. Falls back to the level captured at App boot.

Functions

get()

get(string $key[, mixed $default = null ]) : mixed
Parameters
$key : string
$default : mixed = null

env_flag()

env_flag(string $name, bool $default) : bool
Parameters
$name : string
$default : bool
Return values
bool

bench_mode_enabled()

bench_mode_enabled() : bool
Return values
bool

site_url()

site_url([string $path = '' ]) : string
Parameters
$path : string = ''
Return values
string

site_host()

site_host() : string
Return values
string

async_logging_enabled()

async_logging_enabled() : bool
Return values
bool

resolve_log_dir()

resolve_log_dir() : string|null
Return values
string|null

debug_logging_enabled()

debug_logging_enabled() : bool
Return values
bool

access_logging_enabled()

access_logging_enabled() : bool
Return values
bool

log_file_for()

log_file_for(string $kind) : string|null
Parameters
$kind : string
Return values
string|null

log_sink_for()

log_sink_for(string $path) : Channel|null
Parameters
$path : string
Return values
Channel|null

log_write()

log_write(string $message[, string $kind = 'debug' ]) : void
Parameters
$message : string
$kind : string = 'debug'

coprocess()

Run a closure in a throwaway child process that HAS the coroutine scheduler, even though the caller does not. This is the escape hatch for parallel I/O from a coroutine-scheduler-OFF worker — i.e. superglobals(true) / enableCoroutine(false) mode (the Symfony/FPM-style lifecycle, where running coroutines in the main worker would race process-wide $_GET/$_POST/$_SESSION and shared framework singletons).

coprocess(callable $taskLogic[, bool $wait = true ]) : mixed

The child is spawned with OpenSwoole's coroutine runtime enabled, so inside $taskLogic you can go() + Channel + hooked I/O (curl, file_get_contents, PDO over the network, Co\System::exec, ...) and they run concurrently. The call BLOCKS until the child finishes (when $wait is true) and returns whatever the child echoed — so serialise structured results (json_encode in the child, json_decode in the caller).

Cost & caveats:

  • One proc-style fork per call (~ms). Worth it when a request needs N genuinely-parallel slow I/O calls; not worth it for a single call or CPU-bound work.
  • The child is a FRESH process — it does NOT inherit your framework container, DB connection pool, or request state. Pass everything it needs as captured variables; do raw I/O inside (it can't reach Symfony services / Doctrine's managed connection).
  • Refused when superglobals(false) (coroutine mode) — there you already have a scheduler, so just go() directly.

Example (3 parallel HTTP fetches from a sequential worker):

$json = coprocess(function () {
    $chan = new \OpenSwoole\Coroutine\Channel(3);
    foreach (['a','b','c'] as $svc) {
        go(function () use ($svc, $chan) {
            $chan->push([$svc => file_get_contents("https://api/$svc")]);
        });
    }
    $out = [];
    for ($i = 0; $i < 3; $i++) { $out += $chan->pop(); }
    echo json_encode($out);            // returned to the caller as a string
});
$data = json_decode($json, true);
Parameters
$taskLogic : callable

The logic to run in the coroutine-enabled child. Receives the OpenSwoole\Process as its argument.

$wait : bool = true

Whether to block until the child completes. Default true.

Return values
mixed —

The child's echoed output (string) when $wait is true.

coproc()

Thin alias for {@see coprocess()} — same fork-a-coroutine-child semantics, so it shares coprocess()'s untestability (forks a child process; only valid in the superglobals(true)+enableCoroutine(false) mode the coverage gate excludes).

coproc(callable $taskLogic) : mixed
Parameters
$taskLogic : callable
Tags
codeCoverageIgnore

jTraceEx()

jTraceEx() - provide a Java style exception trace

jTraceEx(Throwable $e[, array<int, string>|null $seen = null ]) : string
Parameters
$e : Throwable
$seen : array<int, string>|null = null

array passed to recursive calls to accumulate trace lines already seen leave as NULL when calling this function

Return values
string —

of array strings, one entry per trace line

zapi()

zapi() : string
Return values
string

elog()

Logs a message with an optional tag and limit.

elog(string $message[, string $tag = "*" ][, int $limit = 1 ]) : void
Parameters
$message : string

The message to log.

$tag : string = "*"

The tag to associate with the log message. Default is "*".

$limit : int = 1

The limit for the log message. Default is 1.

zlog()

Logs a message with an optional tag and filter.

zlog(mixed $log[, string $tag = "system" ][, mixed $filter = null ][, bool $invert_filter = false ]) : void
Parameters
$log : mixed

The message or data to log.

$tag : string = "system"

The tag to categorize the log entry. Default is "system".

$filter : mixed = null

Optional filter to apply to the log entry.

$invert_filter : bool = false

Whether to invert the filter logic. Default is false.

get_config()

get_config(string $key) : mixed
Parameters
$key : string

get_current_render_time()

Get the current render time since request received and started processing.

get_current_render_time() : float

This function calculates and returns the current render time.

Return values
float —

The current render time in seconds.

indent()

Indend the given text with the given number of spaces

indent(string $string[, int $indend = 4 ]) : string
Parameters
$string : string
$indend : int = 4

Number of lines to indent

Return values
string

purify_array()

Takes an iterator or object, and converts it into an Array.

purify_array(mixed $obj) : array<int|string, mixed>
Parameters
$obj : mixed
Return values
array<int|string, mixed>

uniqidReal()

Generates a unique identifier of a specified length.

uniqidReal([int $length = 13 ]) : string
Parameters
$length : int = 13

The length of the unique identifier to generate. Default is 13.

Return values
string —

The generated unique identifier.

access_log()

Logs access details with the given status and length.

access_log([int $status = 200 ][, int $length = 0 ][, float|null $durationSec = null ]) : void
Parameters
$status : int = 200

The HTTP status code to log.

$length : int = 0

The length of the response content.

$durationSec : float|null = null

response_add_header()

response_add_header(string $key, string $value[, bool $ucwords = true ]) : void
Parameters
$key : string
$value : string
$ucwords : bool = true

response_set_status()

Sets the HTTP response status code.

response_set_status(int $status) : void
Parameters
$status : int

The HTTP status code to set for the response.

response_headers_list()

Retrieves all the response headers.

response_headers_list() : array<int, array{0: string, 1: string}>
Return values
array<int, array{0: string, 1: string}> —

An associative array of all the response headers.

setcookie()

setcookie(string $name[, string $value = "" ][, int $expire = 0 ][, string $path = "" ][, string $domain = "" ][, bool $secure = false ][, bool $httponly = false ][, string $samesite = '' ]) : bool
Parameters
$name : string
$value : string = ""
$expire : int = 0
$path : string = ""
$domain : string = ""
$secure : bool = false
$httponly : bool = false
$samesite : string = ''
Return values
bool

setrawcookie()

setrawcookie(string $name[, string $value = "" ][, int $expire = 0 ][, string $path = "" ][, string $domain = "" ][, bool $secure = false ][, bool $httponly = false ]) : bool
Parameters
$name : string
$value : string = ""
$expire : int = 0
$path : string = ""
$domain : string = ""
$secure : bool = false
$httponly : bool = false
Return values
bool

header()

header(string $header[, bool $replace = true ][, int|null $http_response_code = null ]) : false|void
Parameters
$header : string
$replace : bool = true
$http_response_code : int|null = null
Return values
false|void

http_response_code()

http_response_code([int|null $code = null ]) : int|null
Parameters
$code : int|null = null
Return values
int|null

headers_list()

Retrieves all HTTP headers sent by the server.

headers_list() : array<int, string>

This function returns an array of all the HTTP headers that have been sent by the server. It can be useful for debugging or logging purposes.

Return values
array<int, string> —

An associative array of all the HTTP headers.

headers_sent()

Checks if headers have already been sent and optionally returns the file and line number where the output started.

headers_sent([string|null &$file = null ][, int|null &$line = null ]) : bool
Parameters
$file : string|null = null

Optional. If provided, this will be set to the filename where output started.

$line : int|null = null

Optional. If provided, this will be set to the line number where output started.

Return values
bool —

Returns true if headers have already been sent, false otherwise.

header_remove()

Remove a previously set response header. With no argument, clears all.

header_remove([string|null $name = null ]) : void
Parameters
$name : string|null = null

flush()

Force the current output buffer to the client. In main-worker mode, this switches the response into streaming mode (headers flushed, body chunks written via OpenSwoole). Subsequent echo+flush calls stream incrementally.

flush() : void

ob_flush()

ob_flush() : void

ob_end_flush()

ob_end_flush() : void

ob_implicit_flush()

ob_implicit_flush([bool|int $enable = true ]) : void
Parameters
$enable : bool|int = true

phpinfo()

mod_php-parity phpinfo(): render a self-contained HTML document instead of the CLI SAPI's plain-text dump. Matches the native signature — echoes output and returns true. Wired via uopz in App::__construct(); the renderer lives in \ZealPHP\Diagnostics\PhpInfo.

phpinfo([int $flags = INFO_ALL ]) : bool
Parameters
$flags : int = INFO_ALL

INFO_* bitmask.

Return values
bool

php_sapi_name()

mod_php-parity php_sapi_name(): under the CLI SAPI this natively returns "cli", which legacy apps branch on to disable web-only behavior. When an app opts in via App::sapiName('apache2handler') (or 'fpm-fcgi'), this returns the configured value so such code takes its web path. Default (App::$sapi_name === null) returns the real PHP_SAPI — zero behavior change unless explicitly configured.

php_sapi_name() : string

Note: the PHP_SAPI constant cannot be redefined (uopz_redefine refuses it), so code reading the constant directly still sees "cli". Documented limitation.

Return values
string

filter_input()

mod_php-parity filter_input(): native filter_input() reads PHP's internal SAPI request tables, which OpenSwoole never populates (so it returns null under CLI).

filter_input(int $type, string $var_name[, int $filter = FILTER_DEFAULT ][, array<string, mixed>|int $options = 0 ]) : mixed

This resolves the value from RequestContext ($g) and applies the requested filter.

Parameters
$type : int
$var_name : string
$filter : int = FILTER_DEFAULT
$options : array<string, mixed>|int = 0

filter_input_array()

mod_php-parity filter_input_array(): the array counterpart of filter_input().

filter_input_array(int $type[, array<string, mixed>|int $options = FILTER_DEFAULT ][, bool $add_empty = true ]) : array<string, mixed>
Parameters
$type : int
$options : array<string, mixed>|int = FILTER_DEFAULT
$add_empty : bool = true
Return values
array<string, mixed>

header_register_callback()

mod_php-parity header_register_callback(): native PHP fires the callback when the SAPI is about to send headers — which never happens the normal way under OpenSwoole. ZealPHP stores it per-request (coroutine-safe, in $g->memo) and invokes it once just before the buffered response headers are flushed, so header() calls inside the callback still land. Last registration wins (matches native, which keeps a single callback). Returns false if there's no request context (e.g. called outside a request).

header_register_callback(callable $callback) : bool

Scope note: fires for buffered responses (the common case). Streaming / SSE paths flush headers eagerly and are intentionally excluded, consistent with the framework's buffered-vs-streaming split (e.g. Range/ETag middleware).

Parameters
$callback : callable
Return values
bool

error_log()

mod_php-parity error_log(): under the CLI SAPI native error_log() writes to stderr / the php.ini error_log path. ZealPHP routes message_type 0 (system logger) and 4 (SAPI logger) into the framework's async log (debug.log, or stderr if logging is disabled) so legacy error_log() calls land where the rest of the app's diagnostics go — the "we have elog for error_log" contract.

error_log(string $message[, int $message_type = 0 ][, string|null $destination = null ][, string|null $additional_headers = null ]) : bool
  • type 3 (append to file): honored verbatim — explicit destination intent.
    • type 1 (email): unsupported under the coroutine runtime; logged + false.
    • type 0 / 4: routed to log_write() (debug.log → stderr fallback).

Always lands somewhere (never silently dropped), unlike elog() which gates on debug logging; that's why this routes through log_write() directly.

Parameters
$message : string
$message_type : int = 0
$destination : string|null = null
$additional_headers : string|null = null
Return values
bool

apache_request_headers()

Apache mod_php getallheaders() / apache_request_headers() — return all inbound request headers with canonical (Hyphen-Capitalized) case.

apache_request_headers() : array<string, string>
Return values
array<string, string>

getallheaders()

getallheaders() : array<string, string>
Return values
array<string, string>

apache_response_headers()

Apache mod_php apache_response_headers() — currently set outbound headers.

apache_response_headers() : array<string, string>
Return values
array<string, string>

apache_setenv()

Apache mod_php per-request env table. Backed by Legacy\ApacheContext on G; lifetime = one request. Lazy — only allocated if legacy code calls apache_setenv/getenv/note.

apache_setenv(string $variable, string $value[, bool $walk_to_top = false ]) : bool
Parameters
$variable : string
$value : string
$walk_to_top : bool = false
Return values
bool

apache_getenv()

apache_getenv(string $variable[, bool $walk_to_top = false ]) : string|false
Parameters
$variable : string
$walk_to_top : bool = false
Return values
string|false

apache_note()

Apache mod_php apache_note() — per-request note table. Returns previous value.

apache_note(string $note_name[, string|null $note_value = null ]) : string
Parameters
$note_name : string
$note_value : string|null = null
Return values
string

virtual()

Apache mod_php virtual() — performs an internal subrequest. Not supported in ZealPHP's single-process model; we log once and return false rather than crashing legacy code.

virtual(string $uri) : bool
Parameters
$uri : string
Return values
bool

set_time_limit()

set_time_limit() — OpenSwoole has its own coroutine/worker timeouts and native PHP execution-time limit is irrelevant here. Treated as no-op success.

set_time_limit(int $seconds) : bool
Parameters
$seconds : int
Return values
bool

ignore_user_abort()

ignore_user_abort([bool|null $enable = null ]) : int
Parameters
$enable : bool|null = null
Return values
int

connection_status()

connection_status() : int
Return values
int

connection_aborted()

connection_aborted() : int
Return values
int

output_add_rewrite_var()

Apache's URL-rewrite output handler — not used in ZealPHP. No-op.

output_add_rewrite_var(string $name, string $value) : bool
Parameters
$name : string
$value : string
Return values
bool

output_reset_rewrite_vars()

output_reset_rewrite_vars() : bool
Return values
bool

is_uploaded_file()

is_uploaded_file() — verifies that $filename is one of the temp paths registered in this request's $_FILES. Rejects forged paths from user input.

is_uploaded_file(string $filename) : bool
Parameters
$filename : string
Return values
bool

move_uploaded_file()

move_uploaded_file() — equivalent of Apache+mod_php behavior, gated by is_uploaded_file() and falling back to copy+unlink across filesystems.

move_uploaded_file(string $from, string $to) : bool
Parameters
$from : string
$to : string
Return values
bool

set_error_handler()

Per-coroutine set_error_handler override. The native PHP handler is installed at boot and delegates to G's per-coroutine stack — this override just records the user-space registration without touching the engine.

set_error_handler(callable|null $callback[, int $error_levels = E_ALL ]) : callable|null
Parameters
$callback : callable|null
$error_levels : int = E_ALL
Return values
callable|null

restore_error_handler()

restore_error_handler() : bool
Return values
bool

set_exception_handler()

set_exception_handler(callable|null $callback) : callable|null
Parameters
$callback : callable|null
Return values
callable|null

restore_exception_handler()

restore_exception_handler() : bool
Return values
bool

register_shutdown_function()

Per-request shutdown function — fires after the route handler returns and before the PSR response is emitted, so the function can still call echo/header/http_response_code and have those land in the response.

register_shutdown_function(callable $callback, mixed ...$args) : void
Parameters
$callback : callable
$args : mixed

error_reporting()

Per-coroutine error_reporting. Falls back to the level captured at App boot.

error_reporting([int|null $error_level = null ]) : int
Parameters
$error_level : int|null = null
Return values
int
On this page