README

Extension for FrankenPHP

A blazing-fast FrankenPHP integration for Yii2 applications that provides seamless HTTP/2 and HTTP/3 support, automatic memory management, and real-time capabilities.

Features

✅ Automatic Memory Management: Smart cleanup with configurable memory limits.
✅ Error Handling: Comprehensive error reporting to FrankenPHP worker.
✅ Graceful Shutdown: Automatic worker restart when memory usage is high.
✅ High Performance: Utilize FrankenPHP blazing-fast HTTP server for your Yii2 applications.
✅ HTTP/2 & HTTP/3 Support: Native support for modern HTTP protocols with multiplexing.
✅ Production Ready: Battle-tested with Caddy proven reliability.
✅ PSR-7 Compatible: Full PSR-7 request/response handling through the PSR bridge.
✅ Stateless Design: Memory-efficient stateless application lifecycle.
✅ Zero Configuration: Works out of the box with minimal setup.

Demo

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

Installation

composer require yii2-extensions/franken-php:^0.1.0@dev

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\StatelessApplication;

// 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 StatelessApplication($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

    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
    }
}

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

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']);
    }
}