frankenphp Documentation

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 Copy Chapter

• 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 Copy Chapter

• 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 Copy Chapter

• 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 Copy Chapter

• 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 Copy Chapter

• 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 Copy Chapter

• 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.

Project Copy Chapter

• GitHub Repository
• Docker Hub
• README
• Contributing Guide