FrankenPHP
FrankenPHP is a modern PHP application server written in Go and powered by Caddy. It runs PHP applications with automatic HTTPS, HTTP/2 and HTTP/3, an in-memory worker mode, real-time updates via Mercure, hot reload, and a static-binary deployment story.
This index points AI agents and crawlers at the canonical English documentation. All URLs are absolute. Each Markdown source file carries SEO and LLM-friendly YAML frontmatter (title, description).
Core concepts
- FrankenPHP Classic Mode: drop-in replacement for PHP-FPM and Apache mod_php using a fixed or autoscaling thread pool.
- FrankenPHP Worker Mode: keep your PHP application bootstrapped in memory between requests for lower latency.
- Configuring FrankenPHP: Caddyfile, JSON, environment variables, and php.ini configuration.
- FrankenPHP Internals: thread types, the state machine, the Go/C/PHP CGO boundary, auto-scaling, and per-thread environment sandboxing.
- FrankenPHP Security Model: trust boundaries between Go, C, and PHP (which inputs are untrusted, what the runtime is responsible for, and what is out of scope).
Setup and build
- FrankenPHP Docker Image: build custom images, install PHP extensions and Caddy modules, run as non-root, harden with distroless.
- Compile FrankenPHP From Sources: build on Linux, macOS and FreeBSD with PHP linked as a dynamic library.
- Static Build: create a single self-contained FrankenPHP binary with embedded PHP and Caddy.
- Embedding PHP Apps as Standalone Binaries: ship a pure-PHP, Symfony or Laravel app as one static executable.
- Building Images with GitHub Actions: automate Docker image builds and publication.
Worker mode and extensions
- FrankenPHP Worker Mode: supervisor configuration, restart policies, and integration with Symfony Runtime and Laravel Octane.
- Extension Workers: dedicated PHP thread pool from a Go extension for queues, schedulers, and event listeners.
- Writing PHP Extensions in Go: extension generator, types API, calling PHP from Go, classes, methods, and constants.
Frameworks
- Laravel with FrankenPHP: Docker, local install, Laravel Octane integration, and standalone binaries.
- Symfony with FrankenPHP: Symfony Docker, worker mode, hot reload, AssetMapper, and X-Sendfile.
- WordPress with FrankenPHP: minimal install, production Caddyfile, hot reload via Mercure.
- Migrating from Nginx and PHP-FPM: step-by-step migration of an existing PHP stack.
Real-time and performance features
- Mercure Real-Time Hub: built-in Mercure hub for pushing real-time events to browsers over HTTP.
- HTTP 103 Early Hints: preload critical assets before the final response.
- Hot Reload: refresh PHP, templates, and frontend assets without manual reload.
- X-Sendfile and X-Accel-Redirect: delegate large file delivery to the web server after running PHP.
- Performance Tuning: thread count, worker mode, glibc vs musl, Go runtime, OPcache, Caddyfile options.
Production and observability
- Deploying FrankenPHP in Production: Docker Compose deployments with TLS, reverse proxy, and multi-node setups.
- Known Issues: unsupported PHP extensions, musl caveats, Docker TLS gotchas.
- Observability Overview: Prometheus metrics, structured logs, and the Ember TUI dashboard.
- Prometheus Metrics: exposed metrics for threads, workers, queues, crashes, and restarts.
- Logging: structured logging with frankenphp_log() and error_log() routed through Caddy.