README

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.3

Quick start

Create your FrankenPHP entry point (web/index.php)

<?php

declare(strict_types=1);

// disable PHP automatic session cookie handling
ini_set('session.use_cookies', '0');

require_once dirname(__DIR__) . '/vendor/autoload.php';

use yii2\extensions\frankenphp\FrankenPHP;
use yii2\extensions\psrbridge\http\Application;

// Load environment variables from .env file
$dotenv = Dotenv\Dotenv::createImmutable(dirname(__DIR__));
$dotenv->safeLoad();

// production default (change to 'true' for development)
define('YII_DEBUG', $_ENV['YII_DEBUG'] ?? false);
// production default (change to 'dev' for development)
define('YII_ENV', $_ENV['YII_ENV'] ?? 'prod');

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

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

$runner = new FrankenPHP(new Application($config));

$runner->run();

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

    # compatibility headers to enable X-Sendfile support in PHP frameworks (Yii2/Symfony)
    # 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.

Standalone Binary

We provide static FrankenPHP binaries for Linux and macOS containing PHP 8.4 and most popular PHP extensions.

On Windows, use WSL to run FrankenPHP.

Download FrankenPHP or copy this line into your terminal to automatically install the version appropriate for your platform.

curl https://frankenphp.dev/install.sh | sh
mv frankenphp /usr/local/bin/

To run your application, you can use the following command.

./frankenphp run --config ./Caddyfile --watch

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

For enhanced file upload support in worker environments, use the PSR-7 bridge UploadedFile class instead of the standard Yii2 implementation.

<?php

declare(strict_types=1);

use yii2\extensions\psrbridge\http\{Response, UploadedFile};

final class FileController extends \yii\web\Controller
{
    public function actionUpload(): Response
    {
        $file = UploadedFile::getInstanceByName('avatar');

        if ($file !== null && $file->error === UPLOAD_ERR_OK) {
            $file->saveAs('@webroot/uploads/' . $file->name);
        }

        return $this->asJson(['status' => 'uploaded']);
    }
}

Documentation

For detailed configuration options and advanced usage.

• 📚 Installation Guide
• ⚙️ Configuration Reference
• 🧪 Testing Guide
• 🛠️ Development Guide

Package information

Quality code

Our social networks

License