OxPHP Documentation

OxPHP is a high-performance PHP application server that replaces nginx + PHP-FPM with a single binary — built-in TLS, Brotli compression, rate limiting, health checks, Prometheus metrics, SSE streaming, and persistent worker mode included.

Why OxPHP

A typical PHP application in production is several containers: nginx, PHP-FPM, sometimes a separate TLS proxy and a metrics exporter. Configuration is scattered across them, and making everything work together means keeping socket settings, timeouts, and paths in sync. OxPHP replaces the entire stack with a single container. Inside is one process that accepts HTTP connections, executes PHP, and serves static files.

The server works out of the box with sensible defaults. Fine-tuning is done through environment variables: TLS is enabled with two variables (TLS_CERT, TLS_KEY), rate limiting with one (RATE_LIMIT), and Brotli compression is on by default. No need to edit nginx configs or build separate modules.

On a dedicated internal port, health checks (/health), Prometheus metrics (/metrics), and a configuration snapshot (/config) are available. That is enough for Kubernetes liveness/readiness probes and connecting Grafana, without extra sidecar containers.

Logs are structured JSON: method, path, status, response time, and request ID in every line. They are easy to parse in Loki, Elasticsearch, or any other tool without additional grok patterns.

To try worker mode, where the PHP process is not recreated on every request, set WORKER_MODE_ENABLED=true and ENTRY_FILE=worker.php. The framework initializes once and then handles thousands of requests without reloading. To switch back to classic mode, remove the variable.

OxPHP also includes capabilities that typically require separate tools or third-party libraries:

Getting Started

  • Quick Start — build and run your first OxPHP application in under 5 minutes
  • Installation — system requirements and installation options
  • Docker Guide — Dockerfiles, Compose configuration, volumes, and deployment patterns
  • Command-Line Interface — the oxphp command grammar: serve, run a single PHP script, config, and --user privilege drop

Operations

  • Configuration Reference — complete list of environment variables with defaults and descriptions
  • Health Checks — the /health, /metrics, and /config internal server endpoints
  • Metrics — Prometheus-compatible metrics reference
  • Graceful Shutdown — drain behavior, timeouts, and shutdown sequence

Features

  • Routing — three routing modes: traditional file mapping, framework front-controller, and SPA fallback. Worker mode is an orthogonal execution-model toggle and applies on top of any routing mode
  • Static Files — file cache, MIME detection, ETag/Last-Modified headers, and streaming
  • Worker Mode — persistent PHP processes with automatic soft reset between requests
  • Fiber Multiplexing — handle hundreds of concurrent requests per worker thread with cooperative multitasking
  • Compression — Brotli compression for text-based responses
  • TLS — built-in TLS termination with certificate and key configuration
  • Rate Limiting — per-IP rate limiting with configurable windows and limits
  • Timeouts — header read and request timeouts
  • Access Logging — structured JSON access logs with request ID, method, path, status, and duration
  • Request IDs — automatic X-Request-ID generation and pass-through
  • Error Pages — custom HTML error pages for any HTTP status code
  • SSE — real-time Server-Sent Events streaming from PHP
  • Early Response — send the response immediately and continue background processing
  • Async Promises — run PHP closures on background threads and await results
  • Decorators — intercept function and method calls with PHP 8 attributes
  • Distributed Tracing & APM — W3C Trace Context, OpenTelemetry, auto-instrumentation, and PHP tracing SDK
  • Internal Server — dedicated port for health checks, Prometheus metrics, and live configuration

Security

  • Dot-Path Blocking — automatic blocking of hidden files and directories (.env, .git/, .htaccess)
  • Trusted Proxies — real client IP extraction from Forwarded (RFC 7239) and X-Forwarded-* headers with CIDR-based trust
  • PHP Execution Deny-List — block .php execution at writable public paths (e.g. /uploads/**, or specific legacy scripts) to defeat uploaded-shell attacks on legacy apps
  • Symlink Allow Paths — opt-in allow-list for symlink targets outside DOCUMENT_ROOT; supports Laravel-style storage:link and shared asset volumes without weakening the default symlink-escape protection

PHP

  • HTTP Request API — object-oriented request access via oxphp_http_request(): query params, parsed body, headers, cookies, file uploads, and more
  • Functions — built-in PHP functions provided by OxPHP (oxphp_worker(), oxphp_request_id(), oxphp_server_info(), and more)
  • Superglobals — how $_SERVER, $_GET, $_POST, $_COOKIE, $_FILES, and php://input are populated
  • OPcache and JIT — OPcache configuration and JIT compilation settings

Shared State

Process-wide concurrent primitives so workers can coordinate mutable state without Redis, Memcached, or APCu — everything lives in-process, so per-operation cost is microseconds rather than network round-trips.

  • Overview — registry model, handle lifecycle, and when to reach for shared state
  • Registry — the process-wide registry, entry lifecycle, and introspection
  • Counter — atomic int64 accumulator (get, set, add, compareAndSet)
  • Atomic — atomic int64 with explicit memory-ordering control
  • Flag — atomic boolean for one-shot transitions
  • Once — run-once container with reentrancy-safe factory
  • Mutex — poisoning mutex over a stored value with deadlock detection
  • Channel — bounded, fiber-aware MPMC queue
  • Map — concurrent string-keyed store with batched access
  • Pool — bounded object pool with per-thread affinity
  • Naming Conventions — method-naming cheat sheet across the Shared\* family
  • Observability — Prometheus counters and JSON introspection endpoints
  • Migrating to an External Store — when and how to move to Redis or APCu

Architecture

  • Architecture Overview — how OxPHP works: async HTTP handling, PHP worker pool, request flow, and safety guarantees

Examples

End-to-end recipes for running popular PHP applications on OxPHP — each a complete Docker Compose project with a Dockerfile, a docker-compose.yml, install steps, and the OxPHP-specific notes that stock (nginx + PHP-FPM) docs do not cover.

Found a mistake? Report it →