OxPHP is an asynchronous PHP application server written in Rust —
built for production workloads that demand low latency, high concurrency, and zero-config observability.

Documentation: English · Русский · 中文 · Français · Polski · 日本語

Quick Start · Why OxPHP · Migration · Features · Configuration · Roadmap

Two lines. That's it.

FROM ghcr.io/oxphp/oxphp:0.14.0

COPY --chown=www-data:www-data . /var/www/html/public

Note: By default, DOCUMENT_ROOT is /var/www/html/public — the snippet above copies your app directly into the document root. For Laravel, Symfony, Slim, or any project that already ships a public/ subdirectory, use COPY --chown=www-data:www-data . /var/www/html instead: the framework's own public/ lines up with the default DOCUMENT_ROOT.

docker build -t my-app . && docker run -p 80:80 my-app
curl http://localhost/

No nginx config. No PHP-FPM pool tuning. No process manager. Just your app.

See the full Quick Start guide for more details.

OxPHP replaces nginx + PHP-FPM with a single container. The server works out of the box — TLS, compression, rate limiting, Prometheus metrics, health checks, and structured JSON logs are configured via environment variables.

• One process instead of a stack. HTTP/1.1, HTTP/2, TLS, static files, compression and PHP execution live in one binary. There are no FastCGI sockets, pool files or process managers to keep in sync between containers.
• Threads, not processes. PHP workers are OS threads of a single process (PHP ZTS) and share one OPcache: one worker compiles a file, every worker runs the cached bytecode — see OPcache and JIT.
• Persistent workers when you want them. Worker mode keeps the autoloader, service container and DB connections alive between requests, and fiber multiplexing lets one worker carry many requests while each waits on I/O. It is opt-in: the default mode starts every request from a clean PHP state, as PHP-FPM does.
• Concurrency primitives built in. Async promises for parallel work, and Shared\* in-process counters, maps, channels and mutexes that cover single-host coordination without Redis or APCu.
• Defined behaviour under overload. Requests wait in a bounded queue; one that waits longer than QUEUE_WAIT_TIMEOUT_MS is refused with 529 and Retry-After rather than queuing without limit.
• Observability without sidecars. Prometheus /metrics, liveness/readiness/startup probes, JSON access logs, W3C Trace Context, OpenTelemetry export, APM auto-instrumentation of PDO, mysqli, cURL and Redis, and a per-request profiler all ship in the binary.
• Safe defaults. Hidden files (.env, .git/) return 404, symlink escapes are blocked, a deny-list stops .php execution in upload directories, X-Forwarded-* is honoured only from trusted proxies, and the process drops from root to www-data before serving a request.
• Familiar routing. Three of the four routing modes mirror an nginx try_files setup for a front-controller framework, a classic multi-entry app and a SPA.
• Rust where it matters. The HTTP layer (Tokio, rustls) is Rust; PHP is the stock engine from the official php:*-zts images, so the extensions and OPcache are the ones you already know.

See the full documentation for details.

Most PHP applications move from nginx + PHP-FPM without code changes: the default mode runs each request from a clean PHP state, so the work is translating configuration. The migration guide covers:

• picking a routing mode from your try_files and building the image;
• an nginx / PHP-FPM → OxPHP configuration mapping, including where php.ini settings go;
• behaviour differences to check after the move: wall-clock max_execution_time, php_sapi_name(), default frame headers;
• porting FrankenPHP and RoadRunner workers, and tracking memory instead of restarting on a request count;
• what does not carry over: reverse proxy and WebSocket, HTTP/3, one protocol per port, Linux only.

Formal benchmarks are coming soon. We are working on a reproducible test suite covering req/s, latency (p50/p99), memory usage, and worker throughput under concurrent load.

• Native PHP execution — PHP runs directly inside the server process, in a dedicated thread pool
• Full superglobals support: $_SERVER, $_GET, $_POST, $_COOKIE, $_FILES, php://input — see Superglobals
• HTTP Object API — oxphp_http_request() returns a typed, lazy-loading request object with built-in JSON body parsing, content-detected MIME types for uploads, and a mutable attributes container for middleware — see HTTP Request API
• Worker Runtime API — OxPHP\Server\Worker::current() exposes per-thread introspection (id, requestCount, startTime, memoryUsage, rss, maxMemoryBytes) and the worker entry point (serve) — see Worker class
• Shared OPcache across all workers — one worker compiles a file, every worker uses the cached bytecode — see OPcache and JIT
• PHP extension functions — oxphp_*() helpers for streaming, early response, async, tracing, and request access — see PHP functions reference
• Plugin system with typed event dispatch, priority ordering, and PHP function registration
• Attribute-based decorators — intercept function/method calls via PHP 8+ attributes with zero overhead on undecorated code; supports TARGET_FUNCTION, TARGET_METHOD, TARGET_CLASS — see Decorators
• Fatal-error isolation — a fatal error in one request does not take down the server. The exception is PHP's hard memory limit, on PHP 8.4.27 / 8.5.12 and later: an allocation past it ends the whole process — see Memory limits. A native crash, such as a segmentation fault in PHP or in an extension, is not a fatal error and ends the whole process as well

• Worker mode — persistent PHP workers that stay alive across requests; autoloaders, service containers, and DB connections are initialized once and reused — see Worker mode
• Fiber multiplexing — each worker handles multiple concurrent requests via PHP Fibers; oxphp_sleep() and oxphp_async_await() yield the current fiber instead of blocking the worker thread — see Fiber multiplexing
• Runtime hooks — RUNTIME_HOOKS=sleep,streams,net makes native sleep()/usleep(), blocking TCP reads, stream_select(), connects, TLS waits and reads on local sockets suspend the fiber instead of the worker thread, so unmodified PDO MySQL, mysqli and phpredis code benefits — see Runtime hooks
• Automatic recycling — in worker mode a worker is recycled when it passes WORKER_MAX_MEMORY_MIB, when the application calls Worker::scheduleExit(), or after three consecutive requests come apart, a fatal error being the usual one — see Recycling
• Worker health monitoring — workers that die unexpectedly are automatically detected and replaced; a static pool refills to its configured count, a dynamic one to its minimum
• Early response via oxphp_finish_request() — send the response and keep running background work — see Early response

See the full Async promises guide.

• oxphp_async() / oxphp_async_await() — dispatch closures to a dedicated thread pool for true parallel execution
• Portable serialization for use variables, arguments, and return values — safe cross-thread binary transfer
• Supported types: scalars, strings, arrays (nested), and Shared\* / OxPHP\Shared\Shareable objects. Resources and plain objects are rejected — see Limitations
• Exception & die() safety — exceptions, die(), and exit() are caught and re-thrown as OxPHP\Async\AsyncException
• Timeout support — per-task timeouts with OxPHP\Async\TimeoutException
• oxphp_async_await_all() / oxphp_async_await_race() / oxphp_async_await_any() — batch, race (first settled), and any (first fulfilled, JS Promise.any style) primitives

Process-wide concurrent primitives that let PHP workers coordinate mutable state without Redis, Memcached, or APCu. Everything lives in-process — per-op cost is microseconds, not network round-trips. See the full Shared state guide and observability reference.

• Shared\Counter — atomic int64 accumulator (get, set, add, compareAndSet) — see Counter
• Shared\Atomic — full lock-free int64 primitive (load, store, swap, compareAndSet, fetchAdd/Sub/And/Or/Xor) with explicit memory ordering — see Atomic
• Shared\Flag — atomic bool with compareAndSet for one-shot transitions — see Flag
• Shared\Once — run-once container with reentrancy-safe factory — see Once
• Shared\Mutex — poisoning mutex over a stored value, with reentrancy and cross-thread deadlock detection — see Mutex
• Shared\Channel — bounded MPMC queue, fiber-aware (blocking recv yields the current fiber) — see Channel
• Shared\Map — concurrent int|string-keyed store with batched setMany/getMany and cycle-checked nested values — see Map
• Shared\Pool — bounded object pool with strict per-thread affinity, idle-timeout eviction, and chaos-reclaim on worker death — see Pool
• Shared\Registry — name-keyed handles (Registry::counter('hits', fn() => ...)) so every worker and every request converges on the same entry without external stores — see Registry
• Built-in observability — oxphp_shared_* Prometheus counters and /__ox_shared/{summary,entries,entry,preview,types,graph} JSON endpoints on the internal port
• Refcount + lifecycle safety — handles cannot outlive the registry entry; cycle detector rejects graphs that would leak memory
• When you outgrow it, see Migrating to an external store

• HTTP/1.1 + HTTP/2 on one port — the protocol is auto-detected per connection: prior-knowledge h2c over cleartext, or h2 via ALPN under TLS, with transparent HTTP/1.1 fallback. Flow-control windows are tuned for typical PHP response sizes — see HTTP/2
• TLS 1.3 with ALPN — both HTTP/2 and HTTP/1.1 over TLS — see TLS
• 4 routing modes — Traditional (file mapping + always-on PATH_INFO), Framework (every request to index.php; the original path is in REQUEST_URI, PATH_INFO only for /index.php/extra), SPA (index.html for no-extension paths, hard 404 for missing assets), Worker (static assets from disk, everything else to the persistent worker entry). The first three mirror a familiar nginx try_files configuration — see Routing
• SSE streaming via Content-Type: text/event-stream auto-detection or oxphp_stream_flush() — cooperative with fiber multiplexing — see Server-Sent Events
• Timeouts — header read (HEADER_TIMEOUT_SECONDS, slowloris protection); script execution is bounded by PHP's own max_execution_time / set_time_limit(), answered with 504 — see Timeouts

• LRU file cache for static files (in-memory ≤1 MiB, streaming for larger) — see Static files
• HTTP caching with ETag, Last-Modified, and 304 Not Modified
• Compression for text responses (256 B – 3 MiB range) — Brotli, Zstandard and gzip, negotiated per client — see Compression
• mimalloc allocator for lower allocation latency under contention
• Configurable HTTP server threads — CPU/2 worker threads by default (single-threaded on hosts with fewer than 4 CPUs), tunable via TOKIO_WORKERS

Full guide: Distributed tracing.

• W3C Trace Context — automatic traceparent/tracestate propagation, $_SERVER['OXPHP_TRACE_ID'] for PHP log correlation
• OpenTelemetry — OTLP span export (gRPC/HTTP) with semantic conventions, configurable sampling, batch processing
• APM auto-instrumentation — internal PHP functions across PDO, mysqli, cURL, Redis, Memcached, and file I/O hooked at the engine level; every call becomes a span with zero code changes
• #[OxPHP\Apm\Trace] decorator — annotate any function or method with a PHP 8 attribute to create spans automatically
• PHP tracing SDK — 10 oxphp_apm_*() functions (start, end, attribute, event, error, status, header, trace, trace_id, span_id) for manual span creation, attributes, events, error recording, and trace context propagation
• Prometheus metrics at /metrics — per-worker, zero dependencies — see Metrics
• Health checks at /health/liveness, /health/readiness and /health/startup, with /health aggregating them for dashboards — see Health checks
• Internal server on a separate port for health, metrics, and runtime config — see Internal server
• Structured error logging — PHP errors appear in the server log with php_error_type, php_file, php_line fields
• JSON access logging with optional trace_id/span_id fields (levels: all, error, off via ACCESS_LOG) — see Access logging
• Request ID generation + pass-through (X-Request-ID); trace-derived when OTel enabled — see Request IDs

Full guide: Profiling.

• Per-request profile capture — triggered by cookie (OXPROF), header (X-OxPHP-Profile), query (?__oxprof=), or statistical sampling (PROFILER_SAMPLE_RATE); constant-time token compare
• Four export formats — xhprof (for xhgui), speedscope (for speedscope.app), pprof (Go tools / Pyroscope), collapsed (FlameGraph)
• Rich per-span data — wall-time, CPU time, memory (start/end), events, attributes — nanosecond precision throughout
• PHP SDK — 7 functions (OxPHP\Profile\{start, stop, pause, resume, mark, metric, is_active}) + 7 attributes (4 observer-filter: #[Profile] / #[Exclude] / #[Sample] / #[Tag]; 3 decorators: #[Mark] / #[SlowThreshold] / #[MemoryThreshold])
• Shared tree with APM — both plugins read one Arc<SpanTree>; no double collection; APM continues to export only explicit spans to OTel while the profiler keeps the full tree
• In-memory LRU + disk retention — last PROFILER_RETENTION_COUNT runs always retrievable, token-bucket rate-limited writes, 5 s atomic-rename background trimmer
• HTTP push — ship profiles to xhgui or any collector; 3× exponential backoff (100/200/400 ms) with 5 s wallclock cap; xhgui envelope auto-detect
• Internal HTTP routes at /__profiler/ — 8 endpoints (list / metadata / raw / speedscope redirect / DELETE / config / stats / landing) with optional bearer-token auth and path-traversal validation
• Prometheus metrics — 8 counters + 1 gauge (runs, spans, bytes, disk drops, disk/HTTP saturation drops, push failures, truncated, in-memory runs) via /metrics

• Admission control — a request waits up to QUEUE_WAIT_TIMEOUT_MS for a PHP worker and is refused with 529 + Retry-After past it; the waiting set itself is bounded — see Configuration
• Per-IP rate limiting with X-RateLimit-* headers and 429 responses — see Rate limiting
• Custom error pages — pre-loaded at startup, zero I/O on the hot path — see Error pages
• Graceful shutdown — on SIGTERM/SIGINT in-flight requests get up to DRAIN_TIMEOUT_SECONDS to finish, then are cancelled — see Graceful shutdown
• Path traversal protection — symlink escape detection — see Symlink allow paths
• Trusted proxy support — real client IP extraction from Forwarded (RFC 7239), X-Forwarded-* and, behind Cloudflare, CF-Connecting-IP headers with CIDR-based trust — see Trusted proxies
• Dot-path blocking — returns 404 for hidden files (.env, .git/) with .well-known exception (RFC 8615) — see Dot-path blocking
• Privilege drop — the container starts as root so it can bind port 80, and oxphp drops to www-data (UID 82; 33 in the Debian image) before handling any request; --user overrides the target

flowchart TD
    Client([Client])
    HTTP["Async HTTP server<br/>single- or multi-threaded"]
    Route{Route dispatch}
    Static["Static file<br/>LRU cache"]
    Queue[("Bounded queue<br/>529 on wait timeout")]
    NF["404 Not Found"]
    Pool["Async pool<br/>oxphp_async / oxphp_async_await"]

    Client --> HTTP
    HTTP --> Route
    Route -->|static| Static
    Route -->|miss| NF
    Route -->|PHP| Queue
    Queue --> PhpWorkers
    PhpWorkers -.-> Pool
    Pool --> AsyncWorkers

    subgraph PhpWorkers [PHP workers — dedicated OS threads]
        direction BT
        W1[Worker]
        W2[Worker]
        W3[Worker]
    end

    subgraph AsyncWorkers [Async workers — dedicated OS threads]
        direction BT
        A1[Worker]
        A2[Worker]
        A3[Worker]
    end

• Async HTTP server — multi-threaded by default, tunable via TOKIO_WORKERS
• PHP worker pool — each worker is a dedicated OS thread; a fatal error in one worker does not affect the others, except an allocation past PHP's hard memory limit on PHP 8.4.27 / 8.5.12 and later, which ends the whole process — see Memory limits
• Requests wait in a bounded queue between the HTTP server and the PHP workers; a request that waits longer than QUEUE_WAIT_TIMEOUT_MS for a worker is refused with 529
• Async pool — separate threads for oxphp_async() tasks, preventing slowdowns in the main worker pool
• Worker mode — persistent PHP workers that stay alive between requests; autoloaders and DB connections are shared across all requests handled by that worker

When INTERNAL_ADDR is set, a lightweight HTTP server starts on a separate port:

A port-only INTERNAL_ADDR (e.g. :9090) binds loopback; bind 0.0.0.0:9090 only to expose it. When the listener is reachable off-host without INTERNAL_ALLOW_IPS, the server warns at startup. Access control is by network isolation plus the INTERNAL_ALLOW_IPS CIDR allow-list — there is no bearer token by design, since a token invites exposing the port "because it's protected." Health probes are always reachable so orchestrator liveness/readiness checks never break.

APM depends on OTel and shares its TracerProvider via the plugin service registry. Span collection happens on the PHP worker thread; OTLP export runs off the hot path.

flowchart LR
    subgraph Tokio1 ["Tokio thread — request start"]
        TC["Trace context handler<br/>(priority -95)<br/>generates trace_id / span_id"]
        OTR["OtelRequestHandler (-80)<br/>records start_us,<br/>sets X-Request-ID"]
    end

    subgraph PHP ["PHP worker thread"]
        SDK["PHP tracing SDK<br/>oxphp_apm_*()"]
        DEC["#[OxPHP\\Apm\\Trace]<br/>decorator"]
        HOOKS["APM hooks (34 fn)<br/>PDO · mysqli · cURL<br/>Redis · Memcached · file I/O"]
        STACK[("SpanTree<br/>per request")]
        PHPERR["PHP errors"]
    end

    subgraph Tokio2 ["Tokio thread — request end"]
        OTC["OtelCompleteHandler<br/>builds root server span"]
        APC["ApmCompleteHandler (-70)<br/>reads child spans,<br/>links to root span"]
    end

    subgraph Export ["Background export"]
        BATCH["BatchSpanProcessor<br/>(shared TracerProvider)"]
        OTLP["OTLP exporter<br/>gRPC :4317 / HTTP :4318"]
    end

    TC --> OTR
    OTR --> SDK
    OTR --> DEC
    OTR --> HOOKS
    SDK --> STACK
    DEC --> STACK
    HOOKS --> STACK
    STACK -->|Arc<SpanTree> via profile_tree| APC
    PHPERR -->|structured log| APC
    OTR --> OTC
    OTC --> BATCH
    APC --> BATCH
    BATCH --> OTLP

• Trace context is generated first (priority -95) when TRACE_CONTEXT=true (auto-enabled by OTel). OTel's request handler at -80 records start_us; APM's handler runs at -70.
• One span tree per request — APM hooks, the #[Trace] decorator, and the oxphp_apm_*() SDK record into the same per-request span tree, handed to the complete handler as Arc<SpanTree>.
• Shared TracerProvider — OTel registers otel.provider as a plugin service; APM fetches the same Arc<OnceLock<TracerProvider>> so both plugins export to the same batch processor.
• Off-hot-path export — OTel enqueues the root span into the BatchSpanProcessor, which exports on its own thread, and APM exports child spans from a tokio::spawn task; the HTTP response is returned to the client before spans are sent.
• Provider lifecycle — OTel initializes the BatchSpanProcessor in on_ready() (after the Tokio runtime starts). On shutdown, force_flush() + shutdown() drain pending spans.

All settings are via environment variables — no config files required.

The essentials — what most deployments need to get a service up:

Worker pool, queue, rate limiting, timeouts, TLS tuning, static file caching, compression, access logs, trusted proxies, PHP-execution deny rules, and every plugin-scoped variable live in the consolidated reference — see Configuration for the full table.

Boolean values (case-insensitive, 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. An unset variable or empty assignment (FOO=) falls back to the default, so Docker Compose / Kubernetes substitutions like FOO=${FOO} work cleanly when the host variable is missing.

Plugin-scoped env vars (the OTEL_*, OTEL_APM_*, and SHARED_* families) live in the consolidated configuration reference so there is one source of truth:

• OpenTelemetry (plugin-otel): Configuration → OpenTelemetry. For the export pipeline end-to-end, see the Distributed tracing guide.
• APM (plugin-apm): Configuration → APM. Requires OTEL_ENABLED=true.
• Shared State (plugin-shared): Configuration → Shared State. Concept-level walkthrough lives in the Shared state guide.

# Host (without PHP — stub executor, no PHP execution)
cargo build --release --no-default-features

# Docker (with PHP — full functionality)
docker compose build

LISTEN_ADDR=127.0.0.1:8080 DOCUMENT_ROOT=./www/public ./target/release/oxphp

Items are not ordered by priority. Presence on this list does not guarantee implementation.

oxphp.dev — English · Русский · 中文 · Français · Polski · 日本語

The English source of the documentation also lives in this repository under docs/.

AGPL-3.0

_{Built and evolved with AI under careful human guidance.}