> ## Documentation Index
> Fetch the complete documentation index at: https://developer.upsun.com/llms.txt
> Use this file to discover all available pages before exploring further.

# What it takes to make FrankenPHP a first-class Upsun runtime

> Learn why Upsun built a dedicated FrankenPHP image, how its worker mode differs from PHP-FPM, and what testing with production applications uncovered.


FrankenPHP is joining Upsun as a first-class PHP runtime. The new image supports FrankenPHP 1 with PHP 8.4 and 8.5. It includes extensions, Composer, and a Caddy configuration suited to production.

Until now, you could use FrankenPHP by adding its package to a composable image. That worked for experiments and custom stacks. You still had to assemble and maintain the integration yourself.

With the new image, Upsun maintains the runtime, its default configuration, and its update path. Getting there involved more than packaging a binary. FrankenPHP, PHP, and Caddy had to work as one runtime.

Testing that runtime against real applications improved Blackfire compatibility. It also exposed an early-request bug in FrankenPHP itself. The result is a runtime you can choose without first building the platform integration yourself.

## A package isn't the whole runtime

FrankenPHP is a PHP application server built on top of Caddy.

It replaces a separate web server and PHP FastCGI Process Manager (PHP-FPM) with one service. That service accepts HTTP requests and executes PHP.

This architecture makes the PHP version inside each FrankenPHP build important. FrankenPHP supports PHP 8.2 and later. Maintainers choose the PHP version at build time.

With Upsun's composable image, choosing the FrankenPHP package didn't select that PHP version independently.

The rest of the PHP toolchain has to follow. Your application may need a specific PHP command-line interface, extensions, Composer, and server configuration. These parts need compatible builds and a release process that updates them together.

This is why FrankenPHP needs a dedicated image. Upsun can test and release PHP versions, extensions, and the default Caddy configuration as a unit.

It also shortens the path for runtime fixes. Upsun can update the image directly instead of waiting for an updated Nix package in the composable image.

## What worker mode changes

The most visible difference between FrankenPHP and a conventional PHP-FPM setup is worker mode.

With PHP-FPM, each request starts with a clean application lifecycle. PHP loads your application, constructs its objects, handles the request, and clears that state afterward.

OPcache saves precompiled script bytecode. This avoids loading and parsing the same scripts for every request, but it doesn't preserve your initialized application.

Your framework still loads its configuration and constructs its services for every request.

FrankenPHP's worker mode boots your application once and keeps it in memory. The same process can then handle many requests. This can reduce latency and increase throughput when your application spends significant time starting.

The trade-off is state. Static variables, class static properties, global variables, and in-memory caches can persist between requests.

An application designed around a fresh request lifecycle may need explicit cleanup. The Symfony FrankenPHP Runtime and Laravel Octane reset much of the framework state. You still need to test your own services under the worker model.

FrankenPHP also offers classic mode. It retains the familiar request lifecycle while using Caddy and the integrated FrankenPHP architecture. This gives you a migration path that doesn't require adopting long-running application workers on day one.

## Match the runtime to the workload

Worker mode doesn't make every PHP application faster. The result depends on startup time, the work done for each request, and the number of workers. FrankenPHP recommends load testing with realistic traffic in its [performance guide](https://frankenphp.dev/docs/performance/).

CPU allocation matters. A worker configuration tuned for several cores has little room to show its value on a small instance with a fraction of a CPU. More workers inside the same container don't create more compute capacity.

Persistent connections are a different case. When PHP-FPM serves Server-Sent Events, each open connection can occupy a worker. That worker can't handle another request until the connection closes.

FrankenPHP includes a Mercure hub. It handles subscriber connections without assigning each one to a PHP request worker.

That made FrankenPHP and Mercure a good match for an interactive SymfonyCon application, described in the [SymfonyCon live-connection case study](https://developer.upsun.com/posts/how-we-scaled-live-connections-for-1200-developers-at-symfonycon). Comparisons between FrankenPHP and PHP-FPM still need a workload attached. A conventional request-response application and a service holding hundreds of open connections have different constraints.

For a new project, the choice can start with three questions:

* Does the application spend meaningful time bootstrapping on every request?
* Can the application safely reset state between requests?
* Does the workload involve high concurrency or long-lived connections?

If the answer to all three is no, PHP-FPM remains a predictable and well-tested choice. If application startup or connection handling is a bottleneck, FrankenPHP gives you another execution model to test.

## Production defaults are part of the product

Getting a binary to start is a useful experiment. Operating it in production asks more of the surrounding configuration.

The `frankenphp php-server` command is a shortcut that serves the current directory. For production, a Caddyfile gives you control over workers, routes, logging, and other Caddy features. You load it with `frankenphp run`.

Before the dedicated image, a composable stack left several parts for you to configure. You declared the package, selected PHP and its extensions, defined the web command, and supplied the network settings.

The dedicated image handles the common configuration for you. It starts FrankenPHP and generates Caddy configuration from your Upsun web locations. You can still provide a Caddyfile when your application needs different worker settings or Caddy features.

## Testing it on Blackfire's documentation

Blackfire's documentation site became an early production test for the new runtime. Blackfire already had a FrankenPHP integration, but support was still in beta and incomplete.

Using Blackfire on its documentation site helped expose weak spots. The site moved to the dedicated image with PHP 8.5. The test also enabled the Blackfire probe, monitoring, and continuous profiling.

This was compatibility testing for Blackfire, separate from the reasons for building the image. It uncovered several bugs in the probe. The fixes covered classic and worker modes, request handling, worker detection, and memory leaks, as recorded in the [Blackfire changelog](https://docs.blackfire.io/changelogs/php-probe).

It also exposed a startup edge case in FrankenPHP. Caddy could start its HTTP server before FrankenPHP finished initializing. A request arriving in that window passed the running-state check, then blocked because the regular request channel didn't exist yet. Behind a reverse proxy, those requests appeared as random 499 or 504 responses after a container started.

The fix initializes the request channel when it is declared. Early requests can then wait for the first regular PHP thread and continue instead of hanging. That [patch is now merged into FrankenPHP](https://github.com/php/frankenphp/pull/2612/changes).

The image was also tested with a customer who had hit the same PHP runtime limitation in a composable setup. Their workload provided a better test of worker sizing and production Caddy configuration than a small demonstration project could.

This feedback loop is the less visible part of a runtime image. Packaging puts the software in a container. Running real applications on it establishes which defaults work, how updates reach users, and where failures appear under production traffic.

## Another supported choice for PHP

The dedicated FrankenPHP image doesn't make PHP-FPM obsolete. It gives each model a clearer place on Upsun.

PHP-FPM remains a strong default for applications built around short, stateless requests. FrankenPHP classic mode offers an integrated Caddy and PHP stack while retaining that request lifecycle. Worker mode fits applications that can manage persistent state and benefit from avoiding repeated bootstrapping. FrankenPHP's built-in Mercure hub also makes it a natural option for workloads with many concurrent or long-lived connections.

First-class support means you can make that choice based on the application. The platform takes responsibility for the compatible runtime, extensions, tooling, production defaults, and updates behind it. You still need to test whether worker mode suits your code and resource profile. You no longer need to build the runtime integration before that test can begin.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.