FrankenPHP for PHP developers #

This page is for PHP developers whose code may be served by FrankenPHP, the Caddy web server with PHP compiled into one binary, which exp:velocity can drive (--engine=frankenphp). FrankenPHP is the production-ready alternative to the recommended qbix engine. For PHP code it behaves like PHP-FPM. The full operating guide is FrankenPHP as the Exponential web engine.

Contents #

1. Classic mode: a clean state per request
2. The three engines compared
3. The embedded PHP
4. Starting it for a test
5. What to check in your code

Classic mode: a clean state per request #

FrankenPHP runs PHP in classic mode: a pool of PHP threads inside one process, each request starting from a clean state, exactly as under PHP-FPM. Worker mode, where a PHP script stays alive across requests, is deliberately not offered, because the kernel keeps request state in globals and would leak one request into the next. For your code this means: the static state traps of persistent workers do not apply under FrankenPHP (Static state traps), and you pay the bootstrap cost on every request, as under PHP-FPM.

The three engines compared #

Testing code on frankenphp or php next to qbix separates bugs in your code from state kept between requests (Velocity engines).

The embedded PHP #

FrankenPHP brings its own PHP and extensions; it does not read the machine's php.ini. Settings come from settings/velocity.ini:

Two consequences for developers:

• MySQL needs an explicit socket. Without a machine php.ini there is no default MySQL socket; set it in IniOptions[] or database connections fail (§6.1 of the guide).
• Extensions are those of the binary. A PHP extension your code needs must be in the FrankenPHP build, not only in the machine's PHP; read the guide before you depend on one.

Starting it for a test #

php bin/php/console exp:velocity install --engine=frankenphp --check
php bin/php/console exp:velocity start --engine=frankenphp
php bin/php/console exp:velocity status --all
php bin/php/console exp:velocity stop --engine=frankenphp

install downloads a pinned release and checks its SHA-256 before it is ever run. The engine listens on its own ports ([FrankenPHPSettings] Port=8089, HTTPSPort=8444 by default), so it runs beside the qbix engine. The Caddyfile is generated from velocity.ini on every start (var/vc/frankenphp/run/Caddyfile); logs are under var/vc/frankenphp/log. The engine class is expVelocityFrankenPHP (kernel/classes/expvelocityfrankenphp.php).

What to check in your code #

• No reliance on worker state. Code that only works because a static survived (a cache warmed in a previous request) is slower or wrong here; code that is correct here and wrong under qbix keeps state it should not.
• Paths and the root. As everywhere: EXP_ROOT_DIR or eZSys::rootDir(), not paths derived from a kernel file (The engine archive (phar) for PHP developers).
• Errors. display_errors is off by default in this engine; read PHP errors in the logs and in the debug bar.

Related pages #

• FrankenPHP as the Exponential web engine
• Velocity persistent workers for PHP developers
• Web server and Solr commands
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.