README

Yii Framework

RoadRunner

Supercharge your Yii2 applications with RoadRunner blazing-fast HTTP server
High-performance workers, automatic memory management, and seamless PSR-7 integration

Features

Demo

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

Installation

composer require yii2-extensions/road-runner:^0.4 httpsoft/http-message

Register the HTTP worker and message factories before starting the entry point. See the installation guide for runtime setup.

Basic Usage

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

<?php

declare(strict_types=1);

require __DIR__ . '/../vendor/autoload.php';

use yii2\extensions\psrbridge\http\Application;
use yii2\extensions\roadrunner\RoadRunner;

// 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 __DIR__ . '/../vendor/yiisoft/yii2/Yii.php';

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

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

exit($runner->run());

RoadRunner configuration

Create .rr.yaml in your project root

version: "3"
rpc:
    listen: "tcp://127.0.0.1:6001"
server:
    command: "php web/index.php"
    relay: pipes
http:
    address: "0.0.0.0:8080"
    headers:
        response:
            "Cache-Control": "no-cache"

    middleware:
        - static # serve files first
        - gzip # compress dynamic output

    static:
        dir: web
        forbid:
            - .php
            - .htaccess
    pool:
        num_workers: 1
        supervisor:
            max_worker_memory: 100
jobs:
    pool:
        num_workers: 2
        max_worker_memory: 100
    consume: {}

kv:
    local:
        driver: memory
        config:
            interval: 60
metrics:
    address: "127.0.0.1:2112"

Start the server

# install RoadRunner binary
vendor/bin/rr get

# start the server
./rr serve

Important

Your application will be available at http://127.0.0.1:8080 (or http://localhost:8080) or at the address set in http.address in .rr.yaml.

Development & Debugging

For enhanced debugging capabilities and proper time display in RoadRunner, 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) {
            // validate the file before saving; choose a server-controlled storage name
            $file->saveAs('@runtime/uploads/' . bin2hex(random_bytes(16)) . '.bin');
        }

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

Create the destination directory and apply your application's upload validation before using this example.

Documentation

Practical guides and a complete worker example for RoadRunner and PSR-7 integration.

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

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-roadrunner-worker skill: RoadRunner 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.