FrankenPHP & Modern PHP Runtimes: A Deep Dive into High-Performance PHP

PHP has long been the workhorse of the web, powering millions of websites. However, traditional PHP runtimes like FPM have inherent limitations: each request starts a new process, loads the entire application, and then tears it down. This leads to cold starts and wasted resources. Enter FrankenPHP, a modern PHP application server that reimagines how PHP runs. Built on top of Caddy (a Go-based web server) and the Go library for PHP, FrankenPHP introduces a worker mode that keeps your application in memory across requests. It also supports early hints, HTTP/2 and HTTP/3, automatic HTTPS, and concurrent request handling within a single PHP process. This tutorial will guide you through setting up FrankenPHP, understanding its architecture, and leveraging its features to build high-performance PHP applications. Whether you're running a Laravel API, a Symfony site, or a custom PHP app, FrankenPHP can dramatically reduce latency and improve throughput. We'll cover installation, configuration, worker mode, debugging, and real-world production considerations. By the end, you'll have a solid grasp of how to deploy PHP applications with modern runtimes for maximum performance.

What is FrankenPHP?

FrankenPHP is a modern PHP application server written in Go that integrates with Caddy. It replaces traditional PHP-FPM with a more efficient model. Key features include: worker mode (persistent scripts), early hints (103 status code), support for HTTP/2 and HTTP/3, automatic HTTPS via Let's Encrypt, and the ability to handle concurrent requests within a single PHP process. It's designed to be a drop-in replacement for PHP-FPM, compatible with existing PHP applications. FrankenPHP can also be used as a standalone server or as a Caddy module. Its architecture leverages Go's concurrency model to handle many requests with low overhead.

<?php
// A simple PHP script to demonstrate FrankenPHP's worker mode
// This script will be kept in memory across requests

echo "Hello from FrankenPHP! Request #" . ($_SERVER['REQUEST_ID'] ?? 'unknown') . "\n";
echo "Memory usage: " . memory_get_usage(true) . " bytes\n";

Installation and Setup

Installing FrankenPHP is straightforward. You can download a prebuilt binary from the official GitHub releases or compile from source. For this tutorial, we'll use the binary. First, download the appropriate version for your OS. Then, make it executable and optionally move it to your PATH. Create a simple Caddyfile to configure FrankenPHP. Here's a minimal example:

``` { frankenphp }

localhost:8080 { root * /path/to/your/app php_fastcgi unix//var/run/frankenphp.sock } ```

Then run frankenphp run to start the server. You can also use frankenphp --worker to enable worker mode. For production, you'll want to set up systemd service or use Docker. The official Docker image is available as dunglas/frankenphp.

{
    # Global configuration
    frankenphp
}

localhost:8080 {
    root * /var/www/public
    php_fastcgi unix//var/run/frankenphp.sock
    encode gzip
    file_server
}

Worker Mode Deep Dive

Worker mode is the flagship feature of FrankenPHP. Instead of starting a new PHP process for each request, a single script is loaded once and handles multiple requests sequentially. This dramatically reduces overhead, especially for frameworks with heavy bootstrapping (like Laravel or Symfony). To enable worker mode, add the worker directive to your Caddyfile or pass --worker flag. The script must be a PHP file that returns a callable or uses FrankenPHP\handleRequest function. Here's an example of a worker script:

```php <?php // worker.php require_once __DIR__ . '/vendor/autoload.php';

$app = require_once __DIR__ . '/bootstrap/app.php'; $kernel = $app->make(Illuminate\Contracts\Http\Kernel::class);

return function ($request) use ($kernel) { $response = $kernel->handle($request); $kernel->terminate($request, $response); return $response; }; ```

Then in Caddyfile: php_fastcgi unix//var/run/frankenphp.sock with worker directive. FrankenPHP will keep the script running and pass requests to it.

<?php
// Example worker script for Laravel
require_once __DIR__ . '/vendor/autoload.php';

$app = require_once __DIR__ . '/bootstrap/app.php';
$kernel = $app->make(Illuminate\Contracts\Http\Kernel::class);

return function ($request) use ($kernel) {
    $response = $kernel->handle($request);
    $kernel->terminate($request, $response);
    return $response;
};

Early Hints (103 Status Code)

Early hints allow the server to send preliminary HTTP headers before the final response, enabling the browser to start loading critical resources (like CSS, JS, images) earlier. FrankenPHP supports early hints via the 103 Early Hints status code. To use it, your application must send Link headers with rel=preload or rel=preconnect. FrankenPHP will automatically send these as early hints. For example, in a PHP script:

``php <?php header('Link: </style.css>; rel=preload; as=style'); // ... later generate the full response ``

FrankenPHP will send a 103 response with the Link header before the final 200 response. This can improve perceived performance significantly. You can also configure Caddy to add early hints for static assets.

<?php
// Send early hints for critical CSS
header('Link: </style.css>; rel=preload; as=style');
header('Link: </script.js>; rel=preload; as=script');
// Simulate some work
sleep(1);
echo "<html><head><link rel='stylesheet' href='/style.css'></head><body>Hello</body></html>";

Concurrent Request Handling

Unlike traditional PHP-FPM which uses multiple processes, FrankenPHP can handle multiple concurrent requests within a single PHP process using its Go-based event loop. This is achieved through the FrankenPHP\handleRequest function and coroutines. However, PHP itself is single-threaded, so concurrency is cooperative. You can use FrankenPHP\async to run non-blocking I/O operations. For example:

```php <?php use function FrankenPHP\async;

$result = async(function () { // Simulate non-blocking I/O return file_get_contents('https://api.example.com'); });

echo $result->await(); ```

This allows handling multiple requests while waiting for I/O. Note that this is not parallelism; it's concurrency within a single process. For CPU-bound tasks, you'll still need multiple workers.

<?php
use function FrankenPHP\async;

$promises = [];
foreach (['https://api1.example.com', 'https://api2.example.com'] as $url) {
    $promises[] = async(function () use ($url) {
        return file_get_contents($url);
    });
}

foreach ($promises as $promise) {
    echo $promise->await();
}

Security Best Practices with FrankenPHP

Running PHP in worker mode introduces security considerations. Since the application persists, any global state changes can affect subsequent requests. Ensure you reset global variables and close database connections after each request. Use register_shutdown_function to clean up. Also, be aware of file permissions: the worker runs as the user that started FrankenPHP. Use proper file ownership and avoid running as root. For HTTPS, FrankenPHP automatically provisions Let's Encrypt certificates via Caddy. Ensure your domain is correctly configured. Additionally, consider using OPcache to cache compiled PHP files. In worker mode, OPcache is especially beneficial because the cache persists across requests. Configure OPcache with opcache.enable=1 and opcache.revalidate_freq=0 for production.

<?php
// Reset global state after each request
register_shutdown_function(function () {
    // Close database connections
    // Clear global variables
    foreach (get_defined_vars() as $key => $value) {
        unset($GLOBALS[$key]);
    }
});