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