Configuration

FrankenPHP, Caddy as well as the Mercure and Vulcain modules can be configured using the formats supported by Caddy.

In the Docker images, the Caddyfile is located at /etc/caddy/Caddyfile. The static binary will look for the Caddyfile in the directory in which it is started.

PHP itself can be configured using a php.ini file.

By default, PHP supplied with Docker images and the one included in the static binary will look for a php.ini file in the directory where FrankenPHP is started and in /usr/local/etc/php/. They will also load all files ending in .ini from /usr/local/etc/php/conf.d/.

No php.ini file is present by default, you should copy an official template provided by the PHP project.

On Docker, the templates are provided in the images:

  1. FROM dunglas/frankenphp
  3. # Production:
  4. RUN cp $PHP_INI_DIR/php.ini-production $PHP_INI_DIR/php.ini
  6. # Or developement:
  7. RUN cp $PHP_INI_DIR/php.ini-development $PHP_INI_DIR/php.ini

If you don’t use Docker, copy one of php.ini-production or php.ini-development provided in the PHP sources.

Caddyfile Config

To register the FrankenPHP executor, the frankenphp global option must be set, then the php_server or the php HTTP directives may be used within the site blocks to serve your PHP app.

Minimal example:

  1. {
  2.     # Enable FrankenPHP
  3.     frankenphp
  4. }
  6. localhost {
  7.     # Enable compression (optional)
  8.     encode zstd br gzip
  9.     # Execute PHP files in the current directory and serve assets
  10.     php_server
  11. }

Optionally, the number of threads to create and worker scripts to start with the server can be specified under the global option.

  1. {
  2.     frankenphp {
  3.         num_threads <num_threads> # Sets the number of PHP threads to start. Default: 2x the number of available CPUs.
  4.         worker {
  5.             file <path> # Sets the path to the worker script.
  6.             num <num> # Sets the number of PHP threads to start, defaults to 2x the number of available CPUs.
  7.             env <key> <value> # Sets an extra environment variable to the given value. Can be specified more than once for multiple environment variables.
  8.             watch <path> # Sets the path to watch for file changes. Can be specified more than once for multiple paths.
  9.         }
  10.     }
  11. }
  13. # ...

Alternatively, you may use the one-line short form of the worker option:

  1. {
  2.     frankenphp {
  3.         worker <file> <num>
  4.     }
  5. }
  7. # ...

You can also define multiple workers if you serve multiple apps on the same server:

  1. {
  2.     frankenphp {
  3.         worker /path/to/app/public/index.php <num>
  4.         worker /path/to/other/public/index.php <num>
  5.     }
  6. }
  8. app.example.com {
  9.     root * /path/to/app/public
  10.     php_server
  11. }
  13. other.example.com {
  14.     root * /path/to/other/public
  15.     php_server
  16. }
  18. # ...

Using the php_server directive is generally what you need, but if you need full control, you can use the lower level php directive:

Using the php_server directive is equivalent to this configuration:

  1. route {
  2.     # Add trailing slash for directory requests
  3.     @canonicalPath {
  4.         file {path}/index.php
  5.         not path */
  6.     }
  7.     redir @canonicalPath {path}/ 308
  8.     # If the requested file does not exist, try index files
  9.     @indexFiles file {
  10.         try_files {path} {path}/index.php index.php
  11.         split_path .php
  12.     }
  13.     rewrite @indexFiles {http.matchers.file.relative}
  14.     # FrankenPHP!
  15.     @phpFiles path *.php
  16.     php @phpFiles
  17.     file_server
  18. }

The php_server and the php directives have the following options:

  1. php_server [<matcher>] {
  2.     root <directory> # Sets the root folder to the site. Default: `root` directive.
  3.     split_path <delim...> # Sets the substrings for splitting the URI into two parts. The first matching substring will be used to split the "path info" from the path. The first piece is suffixed with the matching substring and will be assumed as the actual resource (CGI script) name. The second piece will be set to PATH_INFO for the script to use. Default: `.php`
  4.     resolve_root_symlink false # Disables resolving the `root` directory to its actual value by evaluating a symbolic link, if one exists (enabled by default).
  5.     env <key> <value> # Sets an extra environment variable to the given value. Can be specified more than once for multiple environment variables.
  6.     file_server off # Disables the built-in file_server directive.
  7. }

Watching for File Changes

Since workers only boot your application once and keep it in memory, any changes to your PHP files will not be reflected immediately.

Workers can instead be restarted on file changes via the watch directive. This is useful for development environments.

  1. {
  2.     frankenphp {
  3.         worker {
  4.             file  /path/to/app/public/worker.php
  5.             watch
  6.         }
  7.     }
  8. }

If the watch directory is not specified, it will fall back to ./**/*.{php,yaml,yml,twig,env}, which watches all .php, .yaml, .yml, .twig and .env files in the directory and subdirectories where the FrankenPHP process was started. You can instead also specify one or more directories via a shell filename pattern:

  1. {
  2.     frankenphp {
  3.         worker {
  4.             file  /path/to/app/public/worker.php
  5.             watch /path/to/app # watches all files in all subdirectories of /path/to/app
  6.             watch /path/to/app/*.php # watches files ending in .php in /path/to/app
  7.             watch /path/to/app/**/*.php # watches PHP files in /path/to/app and subdirectories
  8.             watch /path/to/app/**/*.{php,twig} # watches PHP and Twig files in /path/to/app and subdirectories
  9.         }
  10.     }
  11. }
  • The ** pattern signifies recursive watching
  • Directories can also be relative (to where the FrankenPHP process is started from)
  • If you have multiple workers defined, all of them will be restarted when a file changes
  • Be wary about watching files that are created at runtime (like logs) since they might cause unwanted worker restarts.

The file watcher is based on e-dant/watcher.

When using HTTP/1.x, it may be desirable to enable full-duplex mode to allow writing a response before the entire body has been read. (for example: WebSocket, Server-Sent Events, etc.)

This is an opt-in configuration that needs to be added to the global options in the Caddyfile:

  1. {
  2.   servers {
  3.     enable_full_duplex
  4.   }
  5. }

Caution

Enabling this option may cause old HTTP/1.x clients that don’t support full-duplex to deadlock. This can also be configured using the CADDY_GLOBAL_OPTIONS environment config:

  1. CADDY_GLOBAL_OPTIONS="servers { enable_full_duplex }"

You can find more information about this setting in the Caddy documentation.

Environment Variables

The following environment variables can be used to inject Caddy directives in the Caddyfile without modifying it:

  • SERVER_NAME: change the addresses on which to listen, the provided hostnames will also be used for the generated TLS certificate
  • CADDY_GLOBAL_OPTIONS: inject global options
  • FRANKENPHP_CONFIG: inject config under the frankenphp directive

As for FPM and CLI SAPIs, environment variables are exposed by default in the $_SERVER superglobal.

The S value of the variables_order PHP directive is always equivalent to ES regardless of the placement of E elsewhere in this directive.

PHP config

To load additional PHP configuration files, the PHP_INI_SCAN_DIR environment variable can be used. When set, PHP will load all the file with the .ini extension present in the given directories.

Enable the Debug Mode

When using the Docker image, set the CADDY_GLOBAL_OPTIONS environment variable to debug to enable the debug mode:

  1. docker run -v $PWD:/app/public \
  2.     -e CADDY_GLOBAL_OPTIONS=debug \
  3.     -p 80:80 -p 443:443 -p 443:443/udp \
  4.     dunglas/frankenphp