Document Rapira and improve FrankenPHP setup (#532)

Author: samdark

src/.vitepress/config.js

@@ -174,6 +174,7 @@ export default {
                                 {text: 'Performance Tuning', link: '/guide/tutorial/performance-tuning'},
                                 {text: 'Using with Event Loop', link: '/guide/tutorial/using-with-event-loop'},
                                 {text: 'Using Yii with FrankenPHP', link: '/guide/tutorial/using-yii-with-frankenphp'},
+                                {text: 'Using Yii with Rapira', link: '/guide/tutorial/using-yii-with-rapira'},
                                 {text: 'Using Yii with RoadRunner', link: '/guide/tutorial/using-yii-with-roadrunner'},
                                 {text: 'Using Yii with Swoole', link: '/guide/tutorial/using-yii-with-swoole'},
                                 {text: 'Docker in Application Templates', link: '/guide/tutorial/docker'},

src/guide/index.md

@@ -138,6 +138,7 @@ We release this guide under the [Terms of Yii Documentation](https://www.yiifram
 - [Performance tuning](tutorial/performance-tuning.md)
 - [Using Yii with event loop](tutorial/using-with-event-loop.md)
 - [Using Yii with FrankenPHP](tutorial/using-yii-with-frankenphp.md)
+- [Using Yii with Rapira](tutorial/using-yii-with-rapira.md)
 - [Using Yii with RoadRunner](tutorial/using-yii-with-roadrunner.md)
 - [Using Yii with Swoole](tutorial/using-yii-with-swoole.md)
 - [Docker in application templates](tutorial/docker.md)

src/guide/structure/entry-script.md

@@ -101,8 +101,9 @@ try {
 
 ## Alternative runtimes
 
-For alternative runtimes such as FrankenPHP, RoadRunner, or Swoole, special entry scripts should be used. See:
+For alternative runtimes such as FrankenPHP, Rapira, RoadRunner, or Swoole, special entry scripts should be used. See:
 
 - [Using Yii with FrankenPHP](../tutorial/using-yii-with-frankenphp.md)
+- [Using Yii with Rapira](../tutorial/using-yii-with-rapira.md)
 - [Using Yii with RoadRunner](../tutorial/using-yii-with-roadrunner.md)
 - [Using Yii with Swoole](../tutorial/using-yii-with-swoole.md)

src/guide/tutorial/using-with-event-loop.md

@@ -10,7 +10,7 @@ There is an alternative way of running an application. Event loop. The idea is t
 and then process a number of requests using it. Such an approach is usually called event loop.
 
 There are multiple tools that could be used to achieve it. Notably, [FrankenPHP](https://frankenphp.dev/), 
-[RoadRunner](https://roadrunner.dev/) and [Swoole](https://www.swoole.com/).
+[Rapira](https://rapira.rs/), [RoadRunner](https://roadrunner.dev/) and [Swoole](https://www.swoole.com/).
 
 ## Event loop implications
 
@@ -56,5 +56,6 @@ while ($request = getRequest()) {
 ## Integrations
 
 - [FrankenPHP](using-yii-with-frankenphp.md)
+- [Rapira](using-yii-with-rapira.md)
 - [RoadRunner](using-yii-with-roadrunner.md)
 - [Swoole](using-yii-with-swoole.md)

src/guide/tutorial/using-yii-with-frankenphp.md

@@ -6,7 +6,11 @@ once per request.
 
 ## Installation
 
-Install the FrankenPHP runner package with Composer:
+The [FrankenPHP runner](https://github.com/yiisoft/yii-runner-frankenphp) requires PHP 8.1–8.5.
+Install FrankenPHP using its [installation instructions](https://frankenphp.dev/docs/), or use the Docker setup
+in the Yii application templates described below.
+
+Install the runner package with Composer:
 
 ```shell
 composer require yiisoft/yii-runner-frankenphp
@@ -15,6 +19,10 @@ composer require yiisoft/yii-runner-frankenphp
 FrankenPHP works especially well in containerized deployments and is the runtime used by the Yii application
 templates Docker setup described in [Docker in application templates](docker.md).
 
+> [!NOTE]
+> This runner is for worker mode. To use FrankenPHP in classic mode, keep `public/index.php` and
+> [yiisoft/yii-runner-http](https://github.com/yiisoft/yii-runner-http), the default HTTP runner in the templates.
+
 ## Configuration
 
 First, configure the worker entry script.
@@ -196,7 +204,15 @@ If you switch fully to worker mode, `public/index.php` and `yiisoft/yii-runner-h
 The exact start command depends on how you run FrankenPHP:
 
 - In the Yii application templates, run `make build` and `make up` after updating `worker.php` and the relevant `Caddyfile`.
-- In a custom setup, start FrankenPHP with the Caddy configuration that points to your application `Caddyfile`.
+- With the standalone binary, run the following command from the directory containing your `Caddyfile`:
+
+```shell
+frankenphp run --config Caddyfile
+```
+
+The example configuration uses `/app` as the application root. Adjust `/app/public`, `/app/worker.php`, and the
+watch path to match your installation. See the [FrankenPHP configuration reference](https://frankenphp.dev/docs/config/)
+for other deployment options.
 
 ## On worker scope
 
@@ -209,12 +225,13 @@ For the general implications of long-running workers, see [Using Yii with event
 ## Worker mode notes
 
 - Use the `MAX_REQUESTS` environment variable to limit how many requests a worker handles before restart.
-- Reset stateful services after each request. See [Yii DI `StateResetter` documentation](https://github.com/yiisoft/di#resetting-services-state).
+- The runner calls `Yiisoft\Di\StateResetter::reset()` after each request. Register resetters for your stateful
+  services as described in the [Yii DI documentation](https://github.com/yiisoft/di#resetting-services-state).
 
 ## Additional configuration
 
 `FrankenPHPApplicationRunner` is configured by default for Yii application templates and follows the
-[dependency container configuration](../../guide/concept/configuration.html#container-configuration) concept.
+[dependency container configuration](../concept/configuration.md#container-configuration) concept.
 
 The constructor allows overriding the default bootstrap, events, DI, params, and error-handler configuration.
 You can also provide a custom config instance with `withConfig()` and a custom container with `withContainer()`.

src/guide/tutorial/using-yii-with-rapira.md

@@ -0,0 +1,124 @@
+# Using Yii with Rapira
+
+[Rapira](https://rapira.rs/) is a PHP application server written in Rust that embeds the PHP interpreter.
+The [Yii Rapira runner](https://github.com/yiisoft/yii-runner-rapira) supports its classic, worker, and dispatcher modes.
+Worker and dispatcher modes initialize the application once per worker and reuse it for subsequent requests.
+See [Using Yii with event loop](using-with-event-loop.md) for the implications of keeping the application in memory.
+
+## Installation
+
+The runner requires PHP 8.4–8.5. Install the Rapira binary following the
+[Rapira installation instructions](https://rapira.rs/docs/intro/installation), using a PHP version supported by the runner.
+The Composer packages provide the Yii integration; the server binary must be installed separately.
+
+Install the runner and its contract package in your Yii application:
+
+```shell
+composer require yiisoft/yii-runner-rapira:@dev rapira/contract:@dev
+```
+
+These stability flags allow the development versions used by the runner's installation instructions.
+
+## Configuration
+
+The following example assumes an application based on `yiisoft/app` or `yiisoft/app-api`, with `App\Environment`
+and `src/bootstrap.php` provided by the template.
+
+### Worker entry script
+
+Create `worker.php` in the application root:
+
+```php
+<?php
+
+declare(strict_types=1);
+
+use App\Environment;
+use Psr\Log\LogLevel;
+use Yiisoft\ErrorHandler\ErrorHandler;
+use Yiisoft\ErrorHandler\Renderer\PlainTextRenderer;
+use Yiisoft\Log\Logger;
+use Yiisoft\Log\StreamTarget;
+use Yiisoft\Yii\Runner\Rapira\RapiraApplicationRunner;
+
+$root = __DIR__;
+
+require_once $root . '/src/bootstrap.php';
+
+$runner = new RapiraApplicationRunner(
+    rootPath: $root,
+    debug: Environment::appDebug(),
+    checkEvents: Environment::appDebug(),
+    environment: Environment::appEnv(),
+    temporaryErrorHandler: new ErrorHandler(
+        new Logger(
+            [
+                (new StreamTarget())->setLevels([
+                    LogLevel::EMERGENCY,
+                    LogLevel::ERROR,
+                    LogLevel::WARNING,
+                ]),
+            ],
+        ),
+        new PlainTextRenderer(),
+    ),
+);
+$runner->run();
+```
+
+The runner creates the container, starts the application, converts incoming requests to PSR-7 requests, and emits
+responses. It detects the Rapira execution mode, so the same entry script can be used with all three modes.
+
+### Server configuration
+
+Create `rapira.toml` next to `worker.php`:
+
+```toml
+[http]
+listen = "127.0.0.1:8000"
+
+[pool]
+entrypoint = "worker.php"
+mode = "worker"
+max_requests = 1000
+```
+
+This configuration listens on the loopback interface and recycles each worker after 1,000 requests.
+For serving files from `public`, follow Rapira's [static file configuration](https://rapira.rs/docs/static-files).
+See the [configuration reference](https://rapira.rs/docs/configuration) for the other server and pool settings.
+
+## Starting a server
+
+Run the following command from the application root:
+
+```shell
+rapira serve
+```
+
+Open `http://127.0.0.1:8000` to access the application. Restart the server after changing application code or configuration.
+
+## Execution modes
+
+Set `mode` in the `[pool]` section of `rapira.toml` to choose how requests are processed:
+
+- `classic` initializes the application for each request, similarly to PHP-FPM.
+- `worker` keeps the application in memory and receives requests through PHP's SAPI superglobals.
+- `dispatcher` keeps the application in memory and receives request objects through Rapira's dispatcher API.
+  The Yii runner processes these requests sequentially within each worker.
+
+See [Rapira execution modes](https://rapira.rs/docs/execution-modes) for details.
+
+## On worker scope
+
+In worker and dispatcher modes, services may retain state between requests. The runner calls
+`Yiisoft\Di\StateResetter::reset()` after each request, but you must configure resetters for your own stateful services.
+See the [Yii DI documentation](https://github.com/yiisoft/di#resetting-services-state).
+
+The `max_requests` setting limits how long a worker lives; it does not replace resetting request-specific state.
+
+## Additional configuration
+
+`RapiraApplicationRunner` uses the application templates' web configuration groups by default. Its constructor accepts
+alternative groups, configuration directories, and a temporary error handler. Use `withConfig()` to supply a custom
+configuration instance or `withContainer()` to supply a PSR-11 container. See the
+[runner documentation](https://github.com/yiisoft/yii-runner-rapira#configuration) for examples.