README

Yii Framework

FrankenPHP

Supercharge your Yii2 applications with FrankenPHP blazing-fast HTTP server
HTTP/2, HTTP/3, automatic memory management, and worker mode for ultimate performance

Features

Demo

Explore the ready-to-run Yii2 + FrankenPHP application template.

Installation

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

Quick start

Create web/index.php in an existing Yii application with its routes and secret request.cookieValidationKey already configured.

<?php

declare(strict_types=1);

use HttpSoft\Message\{ResponseFactory, ServerRequestFactory, StreamFactory, UploadedFileFactory};
use Psr\Http\Message\{
    ResponseFactoryInterface,
    ServerRequestFactoryInterface,
    StreamFactoryInterface,
    UploadedFileFactoryInterface,
};
use yii2\extensions\frankenphp\FrankenPHP;
use yii2\extensions\psrbridge\http\Application;

ini_set('session.use_cookies', '0');

define('YII_DEBUG', filter_var(getenv('YII_DEBUG'), FILTER_VALIDATE_BOOLEAN));
define('YII_ENV', getenv('YII_ENV') ?: 'prod');

require dirname(__DIR__) . '/vendor/autoload.php';
require dirname(__DIR__) . '/vendor/yiisoft/yii2/Yii.php';

$config = require dirname(__DIR__) . '/config/web.php';

$config['container']['definitions'][ResponseFactoryInterface::class] = ResponseFactory::class;
$config['container']['definitions'][ServerRequestFactoryInterface::class] = ServerRequestFactory::class;
$config['container']['definitions'][StreamFactoryInterface::class] = StreamFactory::class;
$config['container']['definitions'][UploadedFileFactoryInterface::class] = UploadedFileFactory::class;

$runner = new FrankenPHP(new Application($config));
$runner->run();

The runner emits each PSR response and then completes the bridge's finalize() lifecycle exactly once. HEAD omits the response body. Keep request-scoped components out of persistentComponents; lazy sessions remain isolated when useSession=false. See configuration and worker examples.

FrankenPHP configuration

Create Caddyfile in your project root (worker mode)

{
    auto_https off
    admin localhost:2019
    https_port 8443

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

localhost {
    tls ./web/ssl/localhost.pem ./web/ssl/localhost-key.pem

    log

    encode zstd br gzip

    root ./web

    # request hints for frameworks that consume X-Sendfile-Type and X-Accel-Mapping
    # see: https://github.com/php/frankenphp/blob/main/docs/x-sendfile.md
    request_header X-Sendfile-Type x-accel-redirect
    request_header X-Accel-Mapping ../private-files=/private-files

    intercept {
        @sendfile header X-Accel-Redirect *
        handle_response @sendfile {
            root private-files/
            rewrite * {resp.header.X-Accel-Redirect}
            method * GET
            header -X-Accel-Redirect
            file_server
        }
    }

    php_server {
        try_files {path} index.php
    }
}

Warning

Note: Using custom certificates (like tls ./web/ssl/localhost.pem ./web/ssl/localhost-key.pem) avoids browser trust warnings that occur with Caddy's automatic self-signed certificates.
For local development, consider using mkcert to generate trusted local certificates.
If you want to use Caddy's automatic self-signed certificates for local development, you can remove this line.

For Yii, select the response header explicitly. The URI is relative to the interceptor's private-files/ root:

return Yii::$app->response->xSendFile('/report.pdf', 'report.pdf', ['xHeader' => 'X-Accel-Redirect']);

This serves private-files/report.pdf. Authorize access and select the file on the server before returning the response. Yii's default X-Sendfile response header is not matched by this interceptor.

Standalone Binary

Install a worker-capable binary following the official FrankenPHP instructions, then run from the application root:

frankenphp run --config Caddyfile --watch

On Windows, use WSL.

Docker

Alternatively, Docker images are available.

Worker mode

Gitbash/Windows

docker run \
  -e CADDY_GLOBAL_OPTIONS="auto_https off" \
  -e CADDY_SERVER_EXTRA_DIRECTIVES="tls /app/web/ssl/localhost.pem /app/web/ssl/localhost-key.pem" \
  -e FRANKENPHP_CONFIG="worker ./web/index.php" \
  -e SERVER_NAME="https://localhost:8443" \
  -e SERVER_ROOT="./web" \
  -v "//k/yii2-extensions/app-basic:/app" \
  -p 8443:8443 \
  -p 8443:8443/udp \
  --name yii2-frankenphp-worker \
  dunglas/frankenphp

Note: Paths in the example (//k/yii2-extensions/app-basic) are for demonstration purposes only.
Replace them with the actual path to your Yii2 project on your system.

Linux/WSL

docker run \
  -e CADDY_GLOBAL_OPTIONS="auto_https off" \
  -e CADDY_SERVER_EXTRA_DIRECTIVES="tls /app/web/ssl/localhost.pem /app/web/ssl/localhost-key.pem" \
  -e FRANKENPHP_CONFIG="worker ./web/index.php" \
  -e SERVER_NAME="https://localhost:8443" \
  -e SERVER_ROOT="./web" \
  -v $PWD:/app \
  -p 8443:8443 \
  -p 8443:8443/udp \
  --name yii2-frankenphp-worker \
  dunglas/frankenphp

Important

Your application will be available at https://localhost:8443 or at the address set in the Caddyfile.

Development & Debugging

For enhanced debugging capabilities and proper time display in FrankenPHP, install the worker debug extension.

composer require --dev yii2-extensions/worker-debug:^0.1

Add the following to your development configuration (config/web.php):

<?php

declare(strict_types=1);

use yii2\extensions\debug\WorkerDebugModule;

if (YII_ENV_DEV) {
    // configuration adjustments for 'dev' environment
    $config['bootstrap'][] = 'debug';
    $config['modules']['debug'] = [
        'class' => WorkerDebugModule::class,
        // uncomment the following to add your IP if you are not connecting from localhost.
        //'allowedIPs' => ['127.0.0.1', '::1'],
    ];
}

File Upload Handling

Use yii2\extensions\psrbridge\http\UploadedFile in the application's upload model. Validate file content and size, use a server-generated storage name, and check saveAs() before reporting success. See uploads and streaming downloads.

Documentation

Practical guides and complete worker examples for FrankenPHP and request isolation.

The guides and the API reference generated from the PHPDoc in src/ are published at https://yii2-framework.github.io/docs/extensions/franken-php/.

AI assistance

AI agents: read the documentation index and fetch the Markdown version of a page by appending index.md to its URL. The AI agents guide covers skill installation, client setup and verification.

🤖 yii2-frankenphp-worker skill: FrankenPHP worker.
🧭 yii2-framework skill: Yii 22.0 application conventions.

The hosted documentation covers Yii 22.0. If it does not match the installed revision or is unavailable, use the repository guides, the skill source, the source PHPDoc and the changelog.