Configuration Reference

OxPHP is configured entirely through environment variables. There are no configuration files to manage, and every setting has a default, so a zero-configuration deployment works out of the box.

Boolean values

Variables marked as boolean accept a fixed canonical set, case-insensitive and trimmed:

• truthy: on, true, 1, yes
• falsy: off, false, 0, no

Any non-empty value outside that set — typos like ture — fails fast at startup with an error naming the variable. This catches misconfiguration before traffic instead of silently flipping a flag the wrong way.

An unset variable or empty assignment (FOO=) falls back to the documented default. Empty is treated as unset on purpose: Docker Compose / Kubernetes substitution like FOO=${FOO} produces FOO= when the host variable is missing, and that should not refuse to start the server.

Server

PHP workers

Sizing the waiting set

How many requests can usefully wait follows from how fast the pool retires them. With W workers and a handler that takes T milliseconds, the pool admits W / T requests per millisecond, so a budget of B milliseconds can let in about W × B / T waiters. Everything past that waits the whole budget and is refused anyway, holding a connection and a buffered request body the entire time.

The default cannot compute this — service rate is not known at startup — so it is deliberately generous. That fits fast handlers, where the pool drains a deep backlog well inside the budget, and is far too large for slow ones: with 8 workers, the default 1 s budget and a 200 ms handler, only about 40 requests can be admitted in time while the default parks up to 1024.

Setting it near W × B / T turns the surplus into an immediate 529 rather than a 529 a second later. Shortening QUEUE_WAIT_TIMEOUT_MS achieves the same by the other term. The two trade against each other, and on a slow handler the smaller budget is usually the better lever, because it also bounds how long a client waits for the refusal.

The set is bounded a second time, in bytes. Every waiter holds its request body in memory for as long as it waits, so a cap counted in requests leaves the memory they hold to the traffic: the same 1024 waiters cost nothing on bodyless GETs and gigabytes on uploads. QUEUE_MAX_WAITING_BYTES bounds that sum directly — past it a request carrying a body is refused at once rather than parked, while bodyless ones keep waiting normally. An upload-heavy application that should absorb bursts instead of shedding them wants a larger value; a container with a hard memory limit wants a smaller one. Refusals for either cap are counted separately in oxphp_admission_refused_total (waiting_full against the count, waiting_bytes against the memory), so the metric names the knob to reach for.

Keeping headroom for the accept loop

A request holds its connection — and one of the MAX_CONNECTIONS permits — from the moment it arrives until it is answered, whatever it is doing in between. That covers three separate populations, because a queue slot is released the moment a worker picks the request up, before the script runs:

• running in a worker: at least PHP_WORKERS, and more in worker mode, where one thread multiplexes fibers;
• queued, up to QUEUE_CAPACITY;
• parked in admission, up to QUEUE_MAX_WAITING.

Only the third has a ceiling derived from MAX_CONNECTIONS. Keep PHP_WORKERS + QUEUE_CAPACITY + QUEUE_MAX_WAITING below MAX_CONNECTIONS. Past it the failure mode changes for the worse: the accept loop takes a connection permit before it starts serving a connection, so once the PHP path holds them all it parks, and a client arriving then gets no response at all instead of a 529 — which a load balancer cannot tell apart from a dead instance, while the health probe on INTERNAL_ADDR stays green because it does not go through either limit.

The server checks this at startup and warns when the sum reaches the budget, naming every value; oxphp config --check reports the same, without changing its verdict or exit code. Treat clearing the warning as necessary rather than sufficient: idle keep-alive connections, static-file requests and handshakes in progress hold permits too, and none of them can be counted at startup.

Lowering MAX_CONNECTIONS is the usual way into the warning, because the QUEUE_CAPACITY default is sized from the worker count and does not follow it down — 7 workers and MAX_CONNECTIONS=1000 gives 7 + 896 + 500 against a budget of 1000. Note which knob to reach for: raising MAX_CONNECTIONS on its own does not clear it while QUEUE_MAX_WAITING is left at its default, because that default is half of MAX_CONNECTIONS and rises with it — at 7 workers the sum settles at 1799 and the condition only clears from MAX_CONNECTIONS=1800 up. Lower QUEUE_CAPACITY, or set QUEUE_MAX_WAITING explicitly and then raise the budget.

For a dynamic pool (MIN:MAX) the running term is the minimum, the same count the queue defaults are sized from, so a pool grown to its maximum holds more than the sum says.

The comparison counts connections while the budget is spent by requests, so an HTTP/2-heavy deployment can legitimately sit above it: one connection carries up to H2_MAX_CONCURRENT_STREAMS requests, so the same backlog is held by a fraction of the connections. The warning is expected there. A large pool on the stock budget reaches it too — an auto-sized pool of 39 workers gives 39 + 4992 + 4992 against 10 000 — and that one is worth acting on rather than ignoring.

Static vs dynamic workers

Set PHP_WORKERS to a single number for a fixed pool:

Set PHP_WORKERS to MIN:MAX for automatic scaling:

In dynamic mode, OxPHP scales workers up when all are busy and scales down when workers have been idle longer than PHP_WORKERS_IDLE_SECONDS.

Worker Mode

Set WORKER_MODE_ENABLED=true and point ENTRY_FILE at your worker bootstrap script (e.g. ENTRY_FILE=worker.php or ENTRY_FILE=../worker.php). PHP processes then stay alive across requests, keeping bootstrap state (autoloaders, database connections) in memory. Workers are recycled automatically when they exceed WORKER_MAX_MEMORY_MIB, or on demand when the application calls Worker::scheduleExit(). The WORKER_MAX_REQUESTS knob from earlier releases is deprecated and ignored — set neither, or migrate to Worker::scheduleExit().

Deprecated: INDEX_FILE and WORKER_FILE

The legacy INDEX_FILE and WORKER_FILE variables are still parsed for backwards compatibility. When set, they emit a WARN log line at startup and map onto the new model:

If both old and new are set, ENTRY_FILE / WORKER_MODE_ENABLED win. Migrate at your convenience; the deprecated forms will be removed in a future release.

SAPI / PHP

Timeouts

PHP execution time is bounded by PHP's own max_execution_time ini directive (and set_time_limit() at runtime), not an OxPHP env var.

Rate limiting

Security

The special value private expands to all RFC-1918 private networks, loopback, and link-local addresses (IPv4 and IPv6): 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 127.0.0.0/8, 169.254.0.0/16, ::1/128, fc00::/7, fe80::/10.

Clickjacking protection

Clickjacking is an attack where a hostile page embeds your site in an invisible <iframe> and tricks the user into clicking something they can't see: a "yes, delete my account" button, a one-click purchase, an OAuth "authorize" prompt. The defense is to tell the browser who, if anyone, is allowed to frame your pages. FRAME_OPTIONS controls this.

Two headers govern framing — the legacy X-Frame-Options (understood by all browsers) and the modern Content-Security-Policy: frame-ancestors (which supersedes it where both are present) — so OxPHP emits both, and the policy holds on old and new browsers alike. A single FRAME_OPTIONS value maps to a matching pair:

Choosing a value. SAMEORIGIN is the default: it blocks the cross-origin framing that clickjacking actually relies on, while still letting your own pages embed each other — which many apps legitimately do (admin previews, dashboard widgets, payment components hosted on the same origin). Choose DENY when nothing on your site is ever meant to be framed, not even by itself, for the strictest posture. Choose off only when you manage framing yourself through a full Content-Security-Policy your application sets — see below.

Framing external origins. Neither X-Frame-Options value can name a specific allowed origin (ALLOW-FROM was removed from the standard). To permit a named third party to frame your pages, set FRAME_OPTIONS=off and have your application emit its own Content-Security-Policy with an explicit frame-ancestors list, e.g. header("Content-Security-Policy: frame-ancestors 'self' https://partner.example.com");.

Application headers win. The server headers are fallbacks, applied only when the response carries no such header: an application that sets its own X-Frame-Options or Content-Security-Policy via PHP header() keeps it untouched. The two framing headers are treated as one policy, so the server never contradicts the application:

• If your app sets X-Frame-Options, OxPHP skips its frame-ancestors fallback (a server CSP would override your app's choice in modern browsers).
• If your app sets a Content-Security-Policy that contains a frame-ancestors directive, OxPHP skips its X-Frame-Options fallback (a stricter server X-Frame-Options would over-block in legacy browsers that ignore CSP).

The same precedence applies to X-Content-Type-Options, which OxPHP sets to nosniff on every response: an application-set value is kept verbatim. Note that nosniff is the only value that does anything — an application overriding it with anything else silently disables MIME-sniffing protection.

TLS

HTTP/2

Static files

Logging

Observability

OpenTelemetry

APM

When APM is enabled, OxPHP automatically hooks 34 internal PHP functions (PDO, mysqli, cURL, Redis, Memcached, file I/O) to create child spans. The oxphp_apm_*() PHP functions are registered regardless of whether APM is enabled — when disabled, they are safe no-ops.

Async workers

The async worker pool handles fire-and-forget background tasks dispatched from PHP. It is separate from the PHP worker pool and is not required for standard request handling.

A malformed value in any of these three variables (e.g. ASYNC_WORKERS=8x) is a startup error — falling back to a default would silently disable or misconfigure the pool. An exactly-empty value is treated as unset.

Runtime hooks

Hooks take effect inside worker-mode request fibers and async task fibers. Outside a fiber (traditional/framework/SPA request context, CLI) the original native behavior is preserved, including argument validation errors. With the sleep hooks enabled, third-party code calling sleep() stops pinning the worker thread — no code changes required. Cancelling an async task during a hooked sleep unwinds it with OxPHP\Async\AsyncException, and a hooked sleep() always returns 0 (the signal-interruption return value of the native builtin does not arise).

What the streams hook covers

What the streams hook makes cooperative is a blocking read on a PHP socket stream and a wait inside stream_select(). Before counting on it, check that your client waits one of those two ways. Several common ones do not, and for them nothing changes:

• ext/curl. curl_exec() and curl_multi_* talk to sockets themselves, below PHP streams, so the hook never sees them. This covers every HTTP client built on curl — Guzzle with its default handler among them. A curl client can be pointed at the stream wrapper handler instead, which does go through PHP streams.
• socket_select(). That is ext/sockets, a different API on raw descriptors, and it is not hooked. stream_select() is. The same applies to the wait inside stream_socket_accept(), which is not hooked either.
• Streams from socket_export_stream(). They carry a different ops table, private to PHP, which cannot be patched from an extension.
• unix://, udp:// and udg:// streams. Same reason: their ops tables are private to PHP.
• ssl:// and tls:// once crypto is active. Before stream_socket_enable_crypto() succeeds, an SSL stream's reads are delegated to the plain socket read and therefore do suspend; from the handshake onward they do not.
• Connecting and DNS resolution. A client that holds its connection open benefits on every query; connection setup does not.
• MySQL reached through localhost. The MySQL client reads localhost as "use the unix socket", which is not a tcp:// stream — write 127.0.0.1 in the DSN instead. This applies to PDO_MySQL and mysqli alike, and is easy to miss because everything still works, just without the benefit.
• Writes. Only reads wait. Read readiness holds still as long as one fiber owns the descriptor and nothing else drains it, whereas room in the send buffer is granted and withdrawn by the peer, so a fiber woken on writability can find the window closed again by the time the write runs, after which PHP blocks the thread for its full timeout regardless. A write that fills the socket buffer therefore behaves exactly as it does without the hook. In practice this costs little: waiting on a reply is what takes time, not handing a query to the kernel. (Writes are still looked at, for one thing only: which fiber's exchange the connection is currently carrying — see the note on shared connections below. On a connection no other fiber is using, which is every connection in the ordinary case, the write runs the native path untouched.)

Within that scope the hook keeps the native contract: socket timeouts (stream_set_timeout(), default_socket_timeout) apply unchanged, a timed-out read still reports timed_out through stream_get_meta_data(), and stream identity is untouched, so socket_import_stream() and similar keep working. One limit on the timeout: the deadline is only examined once per scheduler tick, so it fires no sooner than the next tick — at best 100 µs in worker mode and 50 µs in the async pool, and longer under load, since a tick lasts as long as whatever the worker is running. The async pool pauses for longer than that when nothing is happening, but not past a deadline it is holding: a read or write deadline shortens the pause to land on itself, so waiting longer does not make the timeout later. With default_socket_timeout at 60 seconds this is not something most deployments can observe.

stream_select() is hooked by waiting on the descriptors its three arrays name and then handing the call to PHP with the timeout set to zero, so PHP still decides everything you can observe: the return count, the rewriting of the arrays down to the ready streams, the warnings, and the argument errors. The wait is skipped — and the call runs exactly as it would without the hook — whenever the arrays hold something the hook will not stand in for: a read stream with data already buffered (which stream_select() answers from the buffer, without looking at a descriptor), a stream that has no descriptor at all, an element that is not a live stream (a closed one left in the array, say — PHP answers that with an error, not a wait), a descriptor the kernel will not watch for readiness at all (a regular file is the usual case, and one counts as ready the moment you ask), or a descriptor at or past FD_SETSIZE, which PHP's own select() refuses outright. That last one is a real ceiling rather than a formality: a busy worker can hold more than 1024 open descriptors, and a stream_select() naming one of them fails the same way with or without the hook.

Shared connections between concurrent fibers

One connection shared between concurrent fibers is safe for the clients OxPHP guards, and gains nothing. This is the normal shape of a worker-mode application rather than an edge case: WordPress, Laravel and Symfony open their database and cache clients once when the worker boots and hand the same ones to every request, and short of rewriting their data-access layer they cannot be asked for one connection per fiber.

A client protocol is a sequence of exchanges — write a command, read the answer — with nothing on the connection marking where one ends. A fiber parked on a read is parked in the middle of an exchange, and a second fiber's command landing there breaks the protocol. The two clients fail at that differently, and neither well: mysqlnd tracks its connection state and refuses the command before sending anything, while phpredis has no such check and the two fibers read each other's replies — one request's data returned to another with no error raised.

A fiber therefore claims a connection before using it, at both of the levels this has to happen at: the socket ops, which keep the bytes in order, and the client entry points of PDO and mysqli, since mysqlnd's refusal comes before any I/O and nothing at the socket can be reached in time to prevent it. Another fiber reaching the same connection waits for it to be given up at the client level, where nothing but the connection's identity is held; at the socket level it does not wait but is refused, the way a socket timeout is refused, because a fiber suspended inside an operation on someone else's stream would be holding a pointer its owner may free. phpredis is guarded at the client level too, method by method, for exactly that reason. What the client level claims is the connection itself and not the PHP object holding it, so a persistent connection reached through several PDO objects counts as one, and a connection opened with PDO::connect() — which returns the driver's own subclass rather than a PDO — is covered like any other.

Read the hook's gain, then, as belonging to connections a fiber opens for itself: an async task making its own HTTP or database calls, a request opening its own client. What a shared connection gets is the worker thread back while it waits, so other requests can run the work that is not on that connection; its own exchanges run one after another, exactly as they do with the hook off. Four boundaries are worth knowing:

1. A fiber that queried once keeps the connection to the end of its request, because the end of the request is the first moment certainly past the end of an exchange. It keeps it while parked on anything else as well, so a request that has queried and then waits on work of its own that needs the same connection is waiting for itself; the two come apart on the bound below instead of proceeding.
2. Waiting is always bounded: by the smaller of max_execution_time and default_socket_timeout. Set neither and that bound is 30 seconds, since a server SAPI takes the engine's defaults — 30 for the first and 60 for the second; it is default_socket_timeout's 60 only where max_execution_time is 0. max_execution_time is read as the request currently has it, since set_time_limit() is how a request states how long it may run; default_socket_timeout is read as the process started with, because it is the default deadline of a socket operation, and a request narrowing it for a call of its own — a common thing for a library to do, and to leave behind — must not shorten this bound for the requests that follow it on the same worker. Past the bound the call falls back on unguarded behaviour and says why in the server log: for PDO and mysqli it is handed to the client, whose own refusal of a command issued mid-exchange is the error the application already handles, while for phpredis, which has no such refusal and would instead read someone else's reply, it raises a RedisException and sends nothing. A socket-level conflict has no bound of its own because it never waits: the operation fails at once the way a timeout does, so stream_get_meta_data() reports timed_out. Two fibers each holding what the other waits for therefore come apart on that bound instead of waiting on each other for good.
3. Some cases are deliberately left uncovered. A statement or result object kept across requests, which no claimed call precedes: PDOStatement::execute() on a statement prepared in an earlier request behaves as it does with no claim at all. Constructing a second handle on a persistent connection while another fiber is mid-exchange on it: PDO checks that a pooled connection is alive before handing it over, that check fails mid-exchange, and PDO answers by dropping the connection. A protocol written by hand on a raw socket — write a command, suspend on something else, read the reply later — since the socket level only refuses while the holder is parked on the reply itself, and between those two points another fiber takes the connection over; the three clients above are covered here by their client-level claim, which a hand-written protocol has no equivalent of. And anything that reaches a connection outside a fiber altogether, such as a destructor run by the engine's cycle collector between requests, which no claim can see.
4. Closing a shared connection while another request is parked reading it ends that request, with a 500 and a log line naming what happened. Claiming keeps two exchanges apart; it cannot keep a connection alive, and the parked request's reply is on a connection that no longer exists — so the honest answer is to end it rather than to hand back whatever the freed memory now holds. Which calls can do this depends on the client, and only one of them waits: mysqli::close() and mysqli_close() are claimed calls, so they wait for the holder and close once that wait is spent, while Redis::close() is claimed too but raises a RedisException rather than closing. Everything else closes at once — fclose() on a raw stream, and, importantly, PDO, which has no close() method at all: a connection is released by dropping the last reference to the handle (unset($pdo), reassigning it, or letting it fall out of scope), and that path runs inside the engine's own object teardown where no claim is consulted. So the reconnect helper that reassigns a shared PDO handle ends the requests parked on the old connection, without the bounded wait its mysqli equivalent gets. The request is told as soon as the close happens rather than at its own read deadline, which for mysqlnd would be mysqlnd.net_read_timeout — a day out of the box. Applications that close a shared connection to force a reconnect (WordPress's $wpdb->check_connection() is the usual one) should expect the requests parked on it at that moment to fail rather than to return the wrong data.

One more boundary: running the hook underneath a userland fiber scheduler (AMPHP, Revolt) falls back to blocking I/O. A fiber started by such a scheduler runs on its own context, which OxPHP's scheduler cannot resume, so the hook detects this and takes the native path rather than corrupting either scheduler. This is about a fiber a userland scheduler starts inside a request. The request's own fiber is one OxPHP drives, and in worker mode it is a real Fiber — Fiber::getCurrent() inside a request returns it — so libraries that only need to tell concurrent requests apart work without any fallback. The same fact is why Revolt refuses to run its event loop from inside a worker-mode request.

Enabling and cost

1, true and all enable every category, streams included. A deployment already setting RUNTIME_HOOKS=1 for the sleep hooks therefore starts hooking sockets on upgrade without any edit of its own; list the categories explicitly (RUNTIME_HOOKS=sleep) if that is not what you want. Enabling streams also patches one entry of PHP's stream ops table in memory at startup; the page is put back the way it was found, but on a platform where its original protection cannot be determined it stays writable — a small loss of hardening, reported in the server log.

Cost, measured: about 3–5 µs per socket round trip on a worker with nothing else parked, about 5–6 µs with 64 fibers parked on descriptors, and about 7–11 µs with 200. Readiness is resolved through a set the kernel keeps between waits, so what the figure tracks is how many descriptors became ready, not how many are waiting. An idle worker waits on those descriptors rather than sleeping for a fixed interval and noticing readiness on its next tick, which matters a great deal: sleeping blind cost roughly 2 ms per round trip instead.

A wide stream_select() carries an overhead the narrow case does not, because every descriptor a call names is registered before the wait and removed after it. Measured with the waiting itself taken out — every descriptor already readable, so the call returns at once and only the overhead remains — it is about 6 µs against 5 µs unhooked at one descriptor, 56 µs against 9 µs at 64, and 130–150 µs against 16–21 µs at 200: roughly 0.65 µs per descriptor.

Read that as a fixed cost per call, not as a slowdown of the same work. A stream_select() that actually waits — which is what a select loop is written for — dwarfs it: a millisecond of waiting makes even the 200-descriptor figure about a tenth of the call, and what it buys is the worker thread, which the unhooked call holds for the whole wait. Two shapes are the exception, and for them the category is better left off: a call over many descriptors that almost never waits, because there is no thread time to recover; and a request that is the event loop, where the thread has nothing else to run anyway. Clients that wait on one connection — mysqlnd, phpredis, the HTTP stream wrappers — sit at the top of the table, where the overhead is around a microsecond.

RUNTIME_HOOKS vs. oxphp_sleep()

The hook does not replace the first-party primitive — they cover different cases:

• Reach for oxphp_sleep() / oxphp_usleep() in code you write. They suspend the fiber in worker mode unconditionally, with no environment flag, and oxphp_sleep() accepts fractional seconds (oxphp_sleep(0.25)) — a precision native sleep() (integer seconds) cannot express.
• Enable RUNTIME_HOOKS=sleep for code you cannot edit — a framework or vendor library that calls native sleep()/usleep() directly. It is off by default, applies only inside a fiber, and keeps the native contract (a hooked sleep() still takes an int and returns 0).

Relying on RUNTIME_HOOKS for your own handlers ties their cooperativeness to a deployment setting rather than the code; prefer the explicit oxphp_sleep() there.

Shared state

In-process concurrency primitives (OxPHP\Shared\Counter, Map, Channel, Mutex, Once, Pool, Atomic, Flag, Registry). See Shared State for the API tour.

Profiling

Sampling profiler that emits xhprof / speedscope traces. See Profiling for output formats and viewer integration.

Example configurations

Development

Production (Framework)

Production (Worker Mode)

TLS

Inspecting active configuration

When the internal server is running, query the /config endpoint to see the resolved configuration:

See also

• Routing — routing modes and ENTRY_FILE behavior
• Health Checks — internal server endpoints
• Metrics — Prometheus-compatible metrics reference
• Graceful Shutdown — how DRAIN_TIMEOUT_SECONDS affects shutdown
• TLS — TLS setup and certificate requirements
• Rate Limiting — per-IP rate limiting details
• Worker Mode — persistent PHP worker architecture
• Compression — Brotli compression details
• Static Files — caching and file serving
• Distributed Tracing & APM — OTel export, auto-instrumentation, and PHP tracing SDK