FrankenPHP

FrankenPHP application runtime

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.

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.9.1 based on PHP 8.4.12 and Caddy server 2.10.2. Virtual machine image includes multiple tools from the PHP ecosystem such as Composer or Symfony CLI. The php command available in hooks and scripts uses frankenphp php-cli under the hood.

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 override the base flags (--no-interaction --no-progress --no-scripts), set the CC_PHP_COMPOSER_FLAGS environment variable.

To install development dependencies, set the CC_PHP_DEV_DEPENDENCIES environment variable to install. This removes the --no-dev flag independently of CC_PHP_COMPOSER_FLAGS.

Use a local Composer version

If you put a composer.phar file at the root of your project, it will be used to install dependencies.

Custom PHP configuration

To load your own PHP configuration directives, put a php.ini file at the root of your project. FrankenPHP will automatically use it.

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. /public/worker.php). The worker script must be located within the webroot directory. It’s supported by design by Laravel Octane and Symfony Runtime projects.

Configurable port

By default, FrankenPHP listens on port 8080. If you want to change it, set the CC_FRANKENPHP_PORT environment variable to your desired port. This is useful if you want to run a service in front of FrankenPHP, such as Redirection.io for example.

Custom FrankenPHP run command

To override the default server behavior, set the CC_RUN_COMMAND environment variable. When defined, it completely replaces the default frankenphp php-server command. Use it to define flags such as --debug, --mercure or --no-compress:

CC_RUN_COMMAND="frankenphp php-server --listen 0.0.0.0:8080 --debug --mercure"

You can also use it to load a custom Caddyfile:

CC_RUN_COMMAND="frankenphp run --config /path/to/Caddyfile"

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"
clever deploy # or clever restart if there is no code change

Learn more about Clever Tasks

Included extensions

FrankenPHP on Clever Cloud comes with a set included PHP extensions: amqp,apcu,ast,bcmath,brotli,bz2,calendar,ctype,curl,dba,dom,exif,fileinfo,filter,ftp,gd,gmp,gettext,iconv,igbinary,imagick,intl,ldap,lz4,mbregex,mbstring,memcache,memcached,mysqli,mysqlnd,opcache,openssl,password-argon2,parallel,pcntl,pdo,pdo_mysql,pdo_pgsql,pdo_sqlite,pdo_sqlsrv,pgsql,phar,posix,protobuf,readline,redis,session,shmop,simplexml,soap,sockets,sodium,sqlite3,ssh2,sysvmsg,sysvsem,sysvshm,tidy,tokenizer,xlswriter,xml,xmlreader,xmlwriter,xz,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

Request Flow: Varnish, Redirection.io, custom proxy

Request Flow automatically chains reverse proxies between port 8080 (public) and your application, managing port allocation with no manual configuration. Supported services are activated by their presence in your project:

Varnish: add a clevercloud/varnish.vcl file or set CC_VARNISH_FILE
Redirection.io: set CC_REDIRECTIONIO_PROJECT_KEY

Both can be active simultaneously. To control the order, set CC_REQUEST_FLOW (e.g. redirectionio,varnish). To add a custom middleware, include custom in the chain and define CC_REQUEST_FLOW_CUSTOM with @@LISTEN_PORT@@ and @@FORWARD_PORT@@ placeholders. To block public access, set CC_REQUEST_FLOW=block.

When at least one middleware is active, your application must listen on port 9000 instead of 8080.

Last updated on January 28, 2026

Did this documentation help you ?

Elixir Go