# PSR bridge

> Transform your Yii2 applications into high-performance, PSR-compliant powerhouses

**Transform your Yii2 applications into high-performance, PSR-compliant powerhouses**

_Supporting traditional SAPI, RoadRunner, FrankenPHP, and worker-based architectures_

Run a Yii application with PSR-7 requests and responses, including long-running workers. The bridge provides a
PSR-15 request handler, Yii request/response adapters, upload conversion, and a streaming SAPI emitter.

## Available deployment options

### High-Performance Worker Mode

Long-running PHP workers for higher throughput and lower latency.

## Features

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

### Installation

Requires the `filter` and `mbstring` PHP extensions. Install a PSR-7/PSR-17
implementation alongside the bridge; the example uses HttpSoft:

```bash
composer require yii2-extensions/psr-bridge:^0.4 httpsoft/http-message
```

See [installation](/docs/extensions/psr-bridge/installation/index.md).

### Quick start

In an existing Yii application, use this entry script in place of the usual `Application::run()`. The example
assumes `web/index.php`, Composer dependencies, and the application's `config/web.php` with its routes and secret
`request.cookieValidationKey` already configured.

```php
<?php

declare(strict_types=1);

use HttpSoft\Message\{ResponseFactory, ServerRequestFactory, StreamFactory, UploadedFileFactory};
use Psr\Http\Message\{ResponseFactoryInterface, StreamFactoryInterface};
use yii2\extensions\psrbridge\creator\ServerRequestCreator;
use yii2\extensions\psrbridge\emitter\SapiEmitter;
use yii2\extensions\psrbridge\http\Application;

ini_set('session.use_cookies', '0');

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

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

$config['container']['definitions'][ResponseFactoryInterface::class] = ResponseFactory::class;
$config['container']['definitions'][StreamFactoryInterface::class] = StreamFactory::class;

$app = new Application($config);
$creator = new ServerRequestCreator(new ServerRequestFactory(), new StreamFactory(), new UploadedFileFactory());

$request = $creator->createFromGlobals();
$response = $app->handle($request);

$emitted = false;

try {
    (new SapiEmitter())->emit($response, $request->getMethod() !== 'HEAD');
    $emitted = true;
} finally {
    $app->finalize($emitted);
}
```

`Application` supplies the bridge request, response, and error handler by default. For a worker, create the
application once and repeat `handle()`, runtime emission, then `finalize()` for each request. Keep file streams
open until emission completes. A PSR-15 host must arrange this extra finalization step.

### Worker lifecycle defaults

`useSession=false` skips eager session opening around bootstrap; session IDs are still isolated on every request.
Keep request-scoped components out of `persistentComponents`.

### Smart Body Parsing

See the configuration guide before changing lifecycle settings or handling JSON bodies created from SAPI globals.

## Documentation

Practical guides and complete examples for PSR-7 integration and the worker
lifecycle.

- 📚 [Installation and Runtime Choices](/docs/extensions/psr-bridge/installation/index.md)
- ⚙️ [Configuration and Request Isolation](/docs/extensions/psr-bridge/configuration/index.md)
- 💡 [Worker Lifecycle, JSON, Uploads, and Downloads](/docs/extensions/psr-bridge/examples/index.md)
- 🔄 [Upgrade Guide](https://github.com/yii2-extensions/psr-bridge/blob/main/UPGRADE.md) and [Migration Checks](/docs/extensions/psr-bridge/migration/index.md)
- 🧪 [Testing Guide](/docs/extensions/psr-bridge/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-psr-bridge-worker skill](/docs/extensions/psr-bridge/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/psr-bridge/blob/main/LICENSE)

## Package

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