Why FrankenPHP?
Traditional PHP deployments rely on multiple moving parts: a web server, PHP-FPM, and external process management. FrankenPHP simplifies this architecture by embedding PHP execution directly into the server. Some key features include:- Faster startup times and reduced per-request overhead compared to PHP-FPM.
- A modern architecture that works for contemporary PHP runtimes and frameworks.
- Fewer services to configure and maintain.
- Support for a worker-based execution model that avoids re-booting the application on every request.
Execution modes
FrankenPHP supports two distinct execution modes. Choosing the right mode depends on your application’s architecture and tolerance for stateful execution.Classic mode
Classic mode behaves similarly to PHP-FPM and is the recommended default for most applications.- Each request runs in a clean, isolated environment
- No application state is shared between requests
- Lifecycle expectations are identical to PHP-FPM
- Safe for existing PHP applications without modification
Worker mode
Worker mode enables long-running PHP worker processes that handle multiple requests over their lifetime.- The application is booted once and kept in memory
- Subsequent requests reuse the already-loaded application
- Significantly reduced cold-start overhead
- Higher throughput and faster response times
Understanding Worker modes
Stateless execution (PHP-FPM and Classic mode)
In traditional PHP execution models every request starts from a clean slate, the application boots, handles the request, then shuts down and there are no variables, objects, or internal state persist between requests. This guarantees isolation and predictability, but it comes with unavoidable overhead as the full boot and teardown cycle happens on every request.Stateful execution (Worker mode)
With Stateful execution in Worker mode, the application is booted once. It remains in memory and handles many requests and internal state persists unless explicitly reset. This improves performance dramatically, but introduces new risks. For example, in a stateful environment:- Mutated variables may leak into later requests
- Static properties and singletons persist
- Cached data may become stale or invalid
- Connection pools or services may behave unexpectedly
Aplications not explicitly designed for long-running workers may require manual state resets between requests, careful handling of static properties and global variables, explicit cleanup logic and auditing of caching and service lifecycles.Tools like Laravel Octane or the Symfony FrankenPHP Runtime are designed to manage this environment safely. They often serve clones of the application or reset the container state between requests to prevent variables from leaking.
Observability and profiling
FrankenPHP is well supported by Blackfire, making it easy to profile and monitor performance in both Classic and Worker modes.See the Blackfire documentation for FrankenPHP integration.
Configuration
FrankenPHP is available as a package in Upsun composable stacks.Classic mode configuration
Worker mode configuration
Using the latest FrankenPHP version
You can request FrankenPHP from the Nix unstable channel to access the latest available version..upsun/config.yaml
Choosing the right mode
- Use Classic mode if you want safety, predictability, and drop-in compatibility with existing PHP applications.
- Use Worker mode if you need maximum performance and are prepared to manage application state explicitly.