FrankenPHP

Overview

FrankenPHP is a fast and modern server for PHP developed by Kevin Dunglas built on top of the Caddy web server. It’s a seamless drop-in replacement for PHP-FPM or Apache with mod_php, designed to enhance your PHP applications with advanced capabilities.

It comes with many extensions and features such as early hints (HTTP 103), real-time capabilities with its built-in Mercure hub. FrankenPHP can also make your Laravel and Symfony projects faster than ever through their official integrations with the worker mode. Deploying PHP applications with FrankenPHP on Clever Cloud is straightforward and requires no complex configuration, nor Docker container.

Note

FrankenPHP is a new runtime. Help us to improve it by reporting any issue or suggestion on the Clever Cloud Community.

Create your FrankenPHP application

To create a new FrankenPHP application, use the Clever Cloud Console or Clever Tools:

clever create --type frankenphp

FrankenPHP applications can’t be deployed on a pico instance, XS is the default instance type

Configure your FrankenPHP application

Mandatory needs

FrankenPHP runtime only requires a working web application, with an index.php or index.html file. If you need to serve files from a specific directory, set the CC_WEBROOT environment variable, relative to the root of your project (default: /).

Learn more about environment variables on Clever Cloud

FrankenPHP version and tools

FrankenPHP currently deployed version on Clever Cloud is 1.4.4 based on PHP 8.4.5 and Caddy server 2.9.1. Virtual machine image includes multiple tools from the PHP ecosystem such as Composer or Symfony CLI.

FrankenPHP PHP info

Composer native support

If a composer.json file is detected at the root of your project, it will be used to install dependencies during building phase with --no-interaction --no-progress --no-scripts --no-dev flags. To use your own, set the CC_PHP_COMPOSER_FLAGSenvironment variable.

To install development dependencies, set the CC_PHP_DEV_DEPENDENCIES environment variable to install.

To use a local Composer to install dependencies, put the composer.phar file at the root of your project

FrankenPHP and Materia KV

Materia KV is Clever Cloud’s distributed serverless key-value store based on FoundationDB, compatible with existing ecosystems such as Redis®, with TTL for sessions support and JSON commands.

To manage Materia KV data with FrankenPHP, use the included redis extension in your PHP code and configure it with your add-on URL, port and token as password. For now, you need to use the tcp mode and 6378 port.

Worker mode

With FrankenPHP worker mode, a script of your project is kept in memory to handle incoming requests in a few milliseconds. Define the path to this script, relative to the root of your project, with the CC_FRANKENPHP_WORKER environment variable (e.g. /worker/script.php). It’s supported by design by Laravel Octane and Symfony Runtime projects.

Custom FrankenPHP run command

Use your own command to run your FrankenPHP application to define flags such as --debug, --mercure or --no-compress. To do so, set the CC_RUN_COMMAND environment variable, starting with frankenphp php-server --listen 0.0.0.0:8080.

If you need to use a service in front of FrankenPHP, use the custom run command to change the FrankenPHP listen port

Use FrankenPHP to execute PHP scripts as Clever Tasks

FrankenPHP can be used to execute PHP scripts. On Clever Cloud, to run such workloads as Clever Tasks, configure an application as Tasks from the Information panel in the Console or with Clever Tools:

clever create --type frankenphp --task "frankenphp php-cli path/to/task.php"

Learn more about Clever Tasks

Included extensions

FrankenPHP on Clever Cloud comes with a set included PHP extensions: apcu, bcmath, bz2, calendar, ctype, curl, dba, dom, exif, fileinfo, filter, ftp, gd, gmp, gettext, iconv, igbinary, imagick, intl, ldap, mbregex, mbstring, mysqli, mysqlnd, opcache, openssl, parallel, pcntl, pdo, pdo_mysql, pdo_pgsql, pdo_sqlite, pgsql, phar, posix, protobuf, readline, redis, session, shmop, simplexml, soap, sockets, sodium, sqlite3, ssh2, sysvmsg, sysvsem, sysvshm, tidy, tokenizer, xlswriter, xml, xmlreader, xmlwriter, zip, zlib, yaml, zstd.

Enable health check during deployment

The healthcheck allows you to limit downtimes. Indeed, you can provide Clever Cloud with paths to check. If these paths return something other than 200, the deployment will fail.

Add one (or several) environment variable as such:

CC_HEALTH_CHECK_PATH=/my/awesome/path

CC_HEALTH_CHECK_PATH_0=/my/awesome/path
CC_HEALTH_CHECK_PATH_1=/my/other/path

The deployment process checks all paths. All of them must reply with a 200 OK response code.

By default, when no environment variable (for ex: APP_HOME) is defined, the monitoring checks your repository root path /.

Example

Using the path listed above, below are the expected logs:

Response from GET /my/awesome/path is 200
Response from GET /my/other/path is 500
Health check failed:
- GET /my/other/path returned 500.
If the deployment fails after this message, please update your configuration and redeploy.

In this example, the first path is OK, but the second one failed. This gives you a hint on what failed in your application.

Best practice for healthcheck endpoints

To make the most of a healthcheck endpoint, have it check your critical dependencies. For example:

execute SELECT 1 + 1; on your database
retrieve a specific Cellar file
ping a specific IP through a VPN

Last updated on April 9, 2025