GitHub

OxPHP Documentation

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

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 compression is on by default. There are no nginx configs to edit and no separate modules to build.

On a dedicated internal port, health checks (/health, plus a dedicated endpoint per Kubernetes probe type), 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 PHP state is not rebuilt 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:

  • Static file serving includes in-memory caching, ETag/Last-Modified, and automatic MIME types.
  • Three routing modes (file-based, framework, and SPA) are chosen by ENTRY_FILE; persistent worker mode replaces them with routing of its own, which hands every request not served as a static file to a .php entry script.
  • Early response sends the response immediately and continues processing in the background.
  • Worker mode runs persistent PHP workers with fiber multiplexing.
  • SSE streaming sends real-time Server-Sent Events from PHP.
  • Async promises execute PHP closures in the background without blocking the worker.
  • Shared state provides process-wide concurrent primitives (Counter, Flag, Once, Mutex, Channel, Map, Pool), so workers can coordinate without Redis or APCu.
  • Decorators intercept calls via PHP 8 attributes.
  • Distributed tracing & APM supports W3C Trace Context and OpenTelemetry, instruments database/HTTP/cache/file calls automatically, and includes a PHP tracing SDK.

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, with serve, run for a single PHP script, config, and the --user privilege drop
  • Migration: how to move from nginx + PHP-FPM, FrankenPHP or RoadRunner (routing modes, configuration mapping, behaviour differences, and what does not carry over)

Operations

Features

  • Routing describes the three routing modes: traditional file mapping, framework front-controller, and SPA fallback. Worker mode is a routing mode of its own that takes their place: it needs a .php ENTRY_FILE and receives every request not served as a static file
  • Static Files: file cache, MIME detection, ETag/Last-Modified headers, and streaming
  • Worker Mode: persistent PHP workers with automatic soft reset between requests
  • Fiber Multiplexing: handle hundreds of concurrent requests per worker thread with cooperative multitasking
  • Compression: Brotli, Zstandard and gzip for text-based responses, negotiated per client
  • 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
  • Profiling: the built-in per-request profiler, with its activation triggers, the PHP SDK and attributes, export formats, and internal routes
  • 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), X-Forwarded-* and, behind Cloudflare, CF-Connecting-IP 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
  • Path Deny Rules: a gitignore-style .oxphpdeny in DOCUMENT_ROOT keeps vendor/, dumps, backups and other files from being served, or hands their requests to the application
  • 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
  • Worker Class: the OxPHP\Server\Worker runtime handle, covering worker introspection, the worker entry point, and per-thread metrics
  • OPcache and JIT: OPcache configuration and JIT compilation settings

Shared State

Process-wide concurrent primitives let workers 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: 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)

Integrations

  • MCP Server: connect the OxPHP documentation to your coding agent over the Model Context Protocol

Examples

End-to-end recipes for running popular PHP applications on OxPHP. Each one is 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 →