Installation guide

Use a FrankenPHP worker runtime with PHP 8.3+ and the filter and mbstring extensions. The adapter supports Yii ~2.0.55 || ^22.0@dev. The selected framework and other dependencies may require a newer PHP version.

Install the packages

Install the adapter and a PSR-7/PSR-17 implementation:

composer require yii2-extensions/franken-php:^0.4 httpsoft/http-message

Retain the resolved versions in the application’s composer.lock. See UPGRADE when changing an existing worker. The adapter has no frontend assets and requires no asset manager.

HttpSoft supplies the factories in the quick start. Another PSR-7/PSR-17 implementation can be used by changing all four factory bindings. Composer installs the PHP adapter; obtain the server separately using the official FrankenPHP installation instructions.

Configure the worker

Create web/index.php using the quick start. It expects the application’s config/web.php, including its routes, components, and a secret request.cookieValidationKey. Keep cookie and CSRF validation appropriate to the application; worker mode does not remove their purpose. Set YII_DEBUG=1 only for development.

Create a Caddyfile in the application root:

{
    frankenphp {
        worker ./web/index.php
    }
}

localhost {
    root * ./web
    php_server
}

Run from that root:

frankenphp run --config Caddyfile

For development watching, TLS, Docker, and optional X-Sendfile delivery, see the README and the FrankenPHP configuration reference. Pin the runtime version in your deployment.

Next steps

• Configuration and lifecycle
• Worker examples
• Migration checks
• Testing