# RoadRunner

> Supercharge your Yii2 applications with RoadRunner blazing-fast HTTP server

**Supercharge your Yii2 applications with RoadRunner blazing-fast HTTP server**

_High-performance workers, automatic memory management, and seamless PSR-7 integration_

## Features

![Feature Overview](/docs/_astro/features.D2ypSbeC.svg)

## Demo

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

## Installation

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

Register the [HTTP worker and message factories](/docs/extensions/road-runner/configuration/index.md#http-worker-and-message-factories) before
starting the entry point. See the [installation guide](/docs/extensions/road-runner/installation/index.md) for runtime setup.

### Basic Usage

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

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

```yaml
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

```bash
# install RoadRunner binary
vendor/bin/rr get

# start the server
./rr serve
```

:::caution[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.

```bash
composer require --dev yii2-extensions/worker-debug:^0.1
```

Add the following to your development configuration (`config/web.php`):

```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
<?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.

- 📚 [Installation Guide](/docs/extensions/road-runner/installation/index.md)
- ⚙️ [Configuration Guide](/docs/extensions/road-runner/configuration/index.md)
- 💡 [Worker Example](#basic-usage)
- 🔄 [Upgrade Guide](https://github.com/yii2-extensions/road-runner/blob/main/UPGRADE.md)
- 🧪 [Testing Guide](/docs/extensions/road-runner/testing/index.md)

## AI assistance

AI agents: use the repository guides and source for the installed revision.
For a [documentation deployment](https://yii2-framework.github.io/docs/) with
`llms.txt`, read that index first. When Markdown export is enabled, append
`index.md` to a page URL. For Yii conventions, use the `yii2-framework` skill
from a local framework documentation checkout.

- 🤖 [yii2-roadrunner-worker skill](/docs/extensions/road-runner/agents/index.md): installation for Claude
  Code, Codex, and OpenCode.

If the hosted sources are unavailable, use the repository guides and locally
available skills.

## Our social networks

[Follow on X](https://x.com/Terabytesoftw)
[Follow on Facebook](https://www.facebook.com/wilmer.arambula.9)
[Join our Subreddit](https://www.reddit.com/r/Yii2/)
[Join on Telegram](https://t.me/yii_framework_in_english)

## License

[License](https://github.com/yii2-extensions/road-runner/blob/main/LICENSE)

## Package

- Source code and issues: [yii2-extensions/road-runner](https://github.com/yii2-extensions/road-runner). Star the repository if the package is useful to you.
- Composer package: [yii2-extensions/road-runner](https://packagist.org/packages/yii2-extensions/road-runner).
- Changelog: [CHANGELOG.md](https://github.com/yii2-extensions/road-runner/blob/main/CHANGELOG.md).