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.

Quick start

Installation

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

Basic Usage

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

<?php

declare(strict_types=1);

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

// production default (change to 'true' for development)
defined('YII_DEBUG') or define('YII_DEBUG', false);

// production default (change to 'dev' for development)
defined('YII_ENV') or define('YII_ENV', 'prod');

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

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

$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

    frankenphp {
        worker ./index.php
    }
}

localhost {
    log

    encode zstd br gzip

    root {$SERVER_ROOT:public/}

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

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.

cd web
./frankenphp php-server --worker index.php

Docker

Docker images require the web directory to be mounted as /app/web and the application root directory as /app.

Alternatively, Docker images are available.

Worker mode

Gitbash/Windows

docker run \
  -e FRANKENPHP_CONFIG="worker ./web/index.php" \
  -e SERVER_ROOT=./web \
  -v "//k/yii2-extensions/basic-frankenphp/Caddyfile:/etc/caddy/Caddyfile" \
  -v "//k/yii2-extensions/basic-frankenphp:/app" \
  -v "//k/yii2-extensions/basic-frankenphp/web:/app/web" \
  -p 80:80 \
  -p 443:443 \
  -p 443:443/udp \
  --name yii2-frankenphp-worker \
  dunglas/frankenphp

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

Linux/WSL

docker run \
  -e FRANKENPHP_CONFIG="worker ./web/index.php" \
  -e SERVER_ROOT=./web \  
  -v $PWD/Caddyfile:/etc/caddy/Caddyfile \
  -v $PWD:/app \
  -v $PWD/web:/app/web \
  -p 80:80 \
  -p 443:443 \
  -p 443:443/udp \
  --name yii2-frankenphp-worker \
  dunglas/frankenphp

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