Roadrunner Bundle

https://github.com/baldinof/roadrunner-bundle
Admin
The Roadrunner Bundle integrates the high-performance PHP application server, RoadRunner, as a...
Tokens:65,036
Snippets:501
Trust Score:8.9
License:MIT
Update:2 days ago
Show doc for...
Tokens:
Raw
### Start RoadRunner with dev config

Source: https://github.com/baldinof/roadrunner-bundle/blob/3.x/README.md

Starts the RoadRunner server using the development configuration file .rr.dev.yaml. Requires copying the dev config file first with 'cp vendor/baldinof/roadrunner-bundle/.rr.dev.yaml .'.

```bash
bin/rr serve -c .rr.dev.yaml
```

--------------------------------

### Configure KV storage in bundle

Source: https://github.com/baldinof/roadrunner-bundle/blob/3.x/README.md

Enables the KV plugin for the RoadRunner Bundle by listing the storage name 'example' under baldinof_road_runner.kv.storages.

```yaml
# config/packages/baldinof_road_runner.yaml
baldinof_road_runner:
  kv:
    storages:
      - example
```

--------------------------------

### Configure RoadRunner KV plugin

Source: https://github.com/baldinof/roadrunner-bundle/blob/3.x/README.md

Sets up the RoadRunner RPC listener and defines the 'example' KV storage with the memory driver. This is required for the bundle's KV adapter to work.

```yaml
# .rr.yaml
rpc:
  listen: tcp://127.0.0.1:6001

kv:
  example:
    driver: memory
    config: { }
```

--------------------------------

### Implement gRPC service interface

Source: https://github.com/baldinof/roadrunner-bundle/blob/3.x/README.md

Example service class implementing the generated CalculatorInterface. The Sum method receives a context and Sum request, returns a Result with the sum of the two inputs.

```php
<?php

namespace App\Grpc;

use Spiral\RoadRunner\GRPC;
use App\Grpc\Generated\Calculator\Sum;
use App\Grpc\Generated\Calculator\Result;
use App\Grpc\Generated\Calculator\CalculatorInterface;

class Calculator implements CalculatorInterface
{
    public function Sum(GRPC\ContextInterface $ctx, Sum $in): Result
    {
        return (new Result())->setResult($in->getA() + $in->getB());
    }
}
```

--------------------------------

### Example dispatching ForceKernelRebootEvent

Source: https://github.com/baldinof/roadrunner-bundle

Example method that dispatches ForceKernelRebootEvent with a reason string, e.g., when an external service becomes unreachable.

```php
use Baldinof\RoadRunnerBundle\Event\ForceKernelRebootEvent;
use Symfony\Contracts\EventDispatcher\EventDispatcherInterface;

public function stashBrokenState(EventDispatcherInterface $dispatcher): void
{
    // ...
    $dispatcher->dispatch(new ForceKernelRebootEvent('external service became unreachable'));
}
```

--------------------------------

### Configuration example for multiple reboot strategies

Source: https://github.com/baldinof/roadrunner-bundle

YAML configuration example showing how to configure multiple reboot strategies in the baldinof_road_runner.kernel_reboot section. The strategy key lists the strategies to chain: on_exception, max_jobs, and memory. Each strategy has its own configuration keys: allowed_exceptions for on_exception, max_jobs and max_jobs_dispersion for max_jobs, and memory_threshold_mb for memory. This configuration triggers automatic instantiation of ChainRebootStrategy.

```yaml
baldinof_road_runner:
  kernel_reboot:
    strategy: [on_exception, max_jobs, memory]
    allowed_exceptions: []            # on_exception
    max_jobs: 1000                    # max_jobs
    max_jobs_dispersion: 0.2          # max_jobs
    memory_threshold_mb: 256          # memory
```

--------------------------------

### Configure Middlewares in YAML

Source: https://github.com/baldinof/roadrunner-bundle/blob/3.x/README.md

Example configuration for registering middlewares. Middlewares must implement Baldinof\RoadRunnerBundle\Http\MiddlewareInterface. They run outside Symfony Kernel::handle() and the stack is resolved at worker start.

```yaml
baldinof_road_runner:
    middlewares:
        - App\Middleware\YourMiddleware
```

--------------------------------

### Install RoadRunner Bundle with Composer

Source: https://github.com/baldinof/roadrunner-bundle/blob/3.x/README.md

Run this command to install the bundle via Composer. If you don't use Symfony Flex, you must also register the bundle in your kernel and copy the default RoadRunner configuration files.

```bash
composer require baldinof/roadrunner-bundle
```

--------------------------------

### Dockerfile for RoadRunner with PHP 8.1

Source: https://github.com/baldinof/roadrunner-bundle/blob/3.x/README.md

Multi-stage Dockerfile to build a production image for a RoadRunner application. Installs PHP extensions (bcmath, intl, opcache, zip, sockets), Composer, and the RoadRunner binary via `rr get-binary`. Sets APP_ENV=prod, warms the cache, exposes port 8080, and starts the server with `rr serve`.

```Dockerfile
# Dockerfile
FROM php:8.1-alpine

RUN apk add --no-cache linux-headers autoconf openssl-dev g++ make pcre-dev icu-dev zlib-dev libzip-dev && \
    docker-php-ext-install bcmath intl opcache zip sockets && \
    apk del --purge autoconf g++ make

WORKDIR /usr/src/app

COPY --from=composer:latest /usr/bin/composer /usr/bin/composer

COPY composer.json composer.lock ./

RUN composer install --no-dev --no-scripts --prefer-dist --no-progress --no-interaction

RUN ./vendor/bin/rr get-binary --location /usr/local/bin

COPY . .

ENV APP_ENV=prod

RUN composer dump-autoload --optimize && \
    composer check-platform-reqs && \
    php bin/console cache:warmup

EXPOSE 8080

CMD ["rr", "serve"]
```

--------------------------------

### Custom Strategy Example

Source: https://github.com/baldinof/roadrunner-bundle

Example of a custom reboot strategy implementation and its configuration. The strategy is referenced by its service id in the `kernel_reboot` configuration node.

```APIDOC
## Custom Strategy Example

### Description
Example of a custom reboot strategy implementation and its configuration. The strategy is referenced by its service id in the `kernel_reboot` configuration node.

### PHP Implementation

```php
<?php

namespace App\Reboot;

use Baldinof\RoadRunnerBundle\Reboot\KernelRebootStrategyInterface;

final class EveryTenRebootStrategy implements KernelRebootStrategyInterface
{
    private int $count = 0;

    public function shouldReboot(): bool
    {
        return 0 === ++$this->count % 10;
    }

    public function clear(): void
    {
    }
}
```

### YAML Configuration

```yaml
baldinof_road_runner:
  kernel_reboot:
    strategy: App\Reboot\EveryTenRebootStrategy
```
```

--------------------------------

### Register bundle without Symfony Flex (full example)

Source: https://github.com/baldinof/roadrunner-bundle

Complete example of registering the bundle in config/bundles.php without Symfony Flex, including the FrameworkBundle. This is the recommended manual registration.

```php
<?php
// config/bundles.php
use Baldinof\RoadRunnerBundle\BaldinofRoadRunnerBundle;

return [
    Symfony\Bundle\FrameworkBundle\FrameworkBundle::class => ['all' => true],
    BaldinofRoadRunnerBundle::class => ['all' => true],
];
```

--------------------------------

### Use KV adapter in Symfony cache pool

Source: https://github.com/baldinof/roadrunner-bundle/blob/3.x/README.md

Configures a Symfony cache pool named 'cache.example' to use the automatically created adapter 'cache.adapter.roadrunner.kv_example'.

```yaml
# config/packages/cache.yaml
framework:
  cache:
    pools:
      cache.example:
        adapter: cache.adapter.roadrunner.kv_example
```

--------------------------------

### Configuration example for on_exception strategy

Source: https://github.com/baldinof/roadrunner-bundle

YAML configuration for the on_exception reboot strategy. Lists allowed exception classes that must not trigger a reboot. The strategy key is 'on_exception'.

```yaml
baldinof_road_runner:
  kernel_reboot:
    strategy: on_exception
    allowed_exceptions:
      - Symfony\Component\HttpKernel\Exception\HttpExceptionInterface
      - Symfony\Component\Serializer\Exception\ExceptionInterface
      - App\Exception\YourDomainException
```

--------------------------------

### WorkerStartEvent listener example (PrimeCacheListener)

Source: https://github.com/baldinof/roadrunner-bundle

Example event subscriber that warms up a cache when the worker starts. Implements EventSubscriberInterface and subscribes to WorkerStartEvent.

```php
<?php

namespace App\EventListener;

use Baldinof\RoadRunnerBundle\Event\WorkerStartEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

final class PrimeCacheListener implements EventSubscriberInterface
{
    public function __construct(private CacheInterface $cache)
    {
    }

    public function onWorkerStart(WorkerStartEvent $event): void
    {
        $this->cache->warmup();
    }

    public static function getSubscribedEvents(): array
    {
        return [WorkerStartEvent::class => 'onWorkerStart'];
    }
}
```

--------------------------------

### Combine kernel_reboot strategies

Source: https://github.com/baldinof/roadrunner-bundle/blob/3.x/README.md

Configuration combining on_exception, max_jobs, and memory reboot strategies. All relevant options are specified together.

```yaml
# config/packages/baldinof_road_runner.yaml
baldinof_road_runner:
    kernel_reboot:
      strategy: [on_exception, max_jobs, memory]
      allowed_exceptions:
        - Symfony\Component\HttpKernel\Exception\HttpExceptionInterface
        - Symfony\Component\Serializer\Exception\ExceptionInterface
        - App\Exception\YourDomainException
      max_jobs: 1000
      max_jobs_dispersion: 0.2
      memory_threshold_mb: 256
```

--------------------------------

### Metrics configuration for baldinof_road_runner

Source: https://github.com/baldinof/roadrunner-bundle/blob/3.x/README.md

Enables metrics collection and defines a counter metric named 'user_login' with a help text. Place in config/packages/baldinof_road_runner.yaml.

```yaml
# config/packages/baldinof_road_runner.yaml
baldinof_road_runner:
  metrics:
    enabled: true
    collect:
      user_login:
        type: counter
        help: "Number of logged in user"
```

--------------------------------

### Recording metrics in a controller

Source: https://github.com/baldinof/roadrunner-bundle

Shows how to record a metric in application code. The bundle handles declare() at worker start; only collect here using the MetricsInterface service.

```php
<?php

namespace App\Controller;

use Spiral\RoadRunner\MetricsInterface;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\JsonResponse;

class AuthController extends AbstractController
{
    public function login(MetricsInterface $metrics): JsonResponse
    {
        // declare() is handled by the bundle at worker start;
        // only collect here
        $metrics->add('user_login', 1);

        return $this->json(['ok' => true]);
    }
}
```

--------------------------------

### Example listener for GrpcTerminateEvent

Source: https://github.com/baldinof/roadrunner-bundle

Shows a listener method that logs information about the finished gRPC call, including the service class, method name, and response size. This is a typical usage example for handling the GrpcTerminateEvent.

```php
public function onGrpcTerminate(GrpcTerminateEvent $event): void
{
    $this->logger->info('gRPC call finished', [
        'service' => $event->getRequest()->getService()::class,
        'method' => $event->getRequest()->getMethod()->getName(),
        'size' => strlen($event->getResponse()),
    ]);
}
```

--------------------------------

### Example listener for WorkerExceptionEvent

Source: https://github.com/baldinof/roadrunner-bundle

Example subscriber method that logs the exception using a logger. Called when WorkerExceptionEvent is dispatched.

```php
public function onWorkerException(WorkerExceptionEvent $event): void
{
    $this->logger->critical('Uncaught worker exception', [
        'exception' => $event->getException(),
    ]);
}
```

--------------------------------

### Register bundle in config/bundles.php

Source: https://github.com/baldinof/roadrunner-bundle

Example of registering the bundle in config/bundles.php without Symfony Flex. The bundle is enabled for all environments.

```php
<?php
// config/bundles.php
return [
    // ...
    Baldinof\RoadRunnerBundle\BaldinofRoadRunnerBundle::class => ['all' => true],
];
```

--------------------------------

### Configure kernel_reboot with always strategy

Source: https://github.com/baldinof/roadrunner-bundle/blob/3.x/README.md

Configuration to use a fresh container on each request by setting the reboot strategy to 'always'.

```yaml
# config/packages/baldinof_road_runner.yaml
baldinof_road_runner:
    kernel_reboot:
      strategy: always
```

--------------------------------

### getSubscribedEvents() method

Source: https://github.com/baldinof/roadrunner-bundle

Subscribes the listener to the WorkerStartEvent, triggering declareMetrics at worker start.

```php
public static function getSubscribedEvents(): array
{
    return [
        WorkerStartEvent::class => 'declareMetrics',
    ];
}
```

--------------------------------

### Declaring middlewares in baldinof_road_runner.yaml

Source: https://github.com/baldinof/roadrunner-bundle

Configuration example for registering middleware service classes. The MiddlewareCompilerPass validates that each configured service implements MiddlewareInterface and pipes it onto MiddlewareStack.

```yaml
# config/packages/baldinof_road_runner.yaml
baldinof_road_runner:
  middlewares:
    - App\Middleware\YourMiddleware
```

--------------------------------

### RoadRunner RPC and metrics endpoint configuration

Source: https://github.com/baldinof/roadrunner-bundle/blob/3.x/README.md

Configures the RPC listener and the Prometheus metrics endpoint address. Place in .rr.yaml.

```yaml
# .rr.yaml
rpc:
  listen: "tcp:127.0.0.1:6001"

metrics:
  address: "0.0.0.0:9180" # prometheus endpoint
```

--------------------------------

### gRPC configuration in .rr.yaml

Source: https://github.com/baldinof/roadrunner-bundle

Required for gRPC mode: set `APP_RUNTIME` to the bundle runtime and configure the `grpc` plugin with generated proto services. The server command starts PHP and the gRPC server listens on TCP port 9001.

```yaml
server:
  command: "php public/index.php"
  env:
    APP_RUNTIME: Baldinof\RoadRunnerBundle\Runtime\Runtime

grpc:
  listen: "tcp://:9001"
  proto:
    - "calculator.proto"

```

--------------------------------

### Configure kernel_reboot with on_exception strategy

Source: https://github.com/baldinof/roadrunner-bundle/blob/3.x/README.md

Configuration for the on_exception reboot strategy. Allows specific exceptions that do not put the app in an errored state, preventing unnecessary kernel reboots.

```yaml
# config/packages/baldinof_road_runner.yaml
baldinof_road_runner:
    kernel_reboot:
      strategy: on_exception
      allowed_exceptions:
        - Symfony\Component\HttpKernel\Exception\HttpExceptionInterface
        - Symfony\Component\Serializer\Exception\ExceptionInterface
        - App\Exception\YourDomainException
```

--------------------------------

### Custom strategy EveryTenRebootStrategy

Source: https://github.com/baldinof/roadrunner-bundle

Example custom strategy that reboots every tenth request. Declare it as a service and reference it by its class name in the kernel_reboot strategy option.

```php
<?php

namespace App\Reboot;

use Baldinof\RoadRunnerBundle\Reboot\KernelRebootStrategyInterface;

final class EveryTenRebootStrategy implements KernelRebootStrategyInterface
{
    private int $count = 0;

    public function shouldReboot(): bool
    {
        return 0 === ++$this->count % 10;
    }

    public function clear(): void
    {
    }
}
```

--------------------------------

### RoadRunner gRPC basic configuration

Source: https://github.com/baldinof/roadrunner-bundle/blob/3.x/README.md

Configures the RoadRunner server to run the PHP application with the RoadRunner Bundle runtime and enables the gRPC plugin listening on port 9001 with the calculator.proto file.

```yaml
server:
  command: "php public/index.php"
  env:
    APP_RUNTIME: Baldinof\RoadRunnerBundle\Runtime\Runtime

grpc:
  listen: "tcp://:9001"

  proto:
    - "calculator.proto"
```

--------------------------------

### TimingMiddleware usage example

Source: https://github.com/baldinof/roadrunner-bundle

Middleware that times requests and adds an X-Timing header. Uses the two-phase generator pattern: yield the response first, then perform heavy non-blocking work after the response is sent.

```php
<?php

namespace App\Middleware;

use Baldinof\RoadRunnerBundle\Http\MiddlewareInterface;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpKernel\HttpKernelInterface;

final class TimingMiddleware implements MiddlewareInterface
{
    public function process(Request $request, HttpKernelInterface $next): \Generator
    {
        $start = microtime(true);

        $response = $next->handle($request);
        $response->headers->set('X-Timing', (string) round((microtime(true) - $start) * 1000, 2));

        yield $response;

        // Heavy, non-blocking work after the response is sent:
        $this->log((microtime(true) - $start) * 1000);
    }

    private function log(float $ms): void { /* ... */ }
}
```

--------------------------------

### HttpWorker start() method signature

Source: https://github.com/baldinof/roadrunner-bundle

Public method that starts the worker loop. It dispatches WorkerStartEvent, processes requests until waitRequest() returns null, handles reboots for RebootableInterface kernels, and dispatches WorkerStopEvent on exit.

```php
public function start(): void
```

--------------------------------

### Runner::run()

Source: https://github.com/baldinof/roadrunner-bundle

Runs the RoadRunner worker. It sets the APP_RUNTIME_MODE, boots the kernel, fetches the worker registry, and starts the appropriate worker. Returns 0 on success or 1 if no worker implementation is registered for the mode.

```APIDOC
## Runner::run()

### Description
Runs the RoadRunner worker. It sets the APP_RUNTIME_MODE, boots the kernel, fetches the worker registry, and starts the appropriate worker. Returns 0 on success or 1 if no worker implementation is registered for the mode.

### Method
PHP method

### Endpoint
`Baldinof\RoadRunnerBundle\Runtime\Runner::run(): int`

### Return
`int` — `0` on success, `1` when no worker implementation is registered for the mode.

### Behavior
1. Sets `$_SERVER['APP_RUNTIME_MODE']` to `sprintf('web=%d&worker=1', $this->mode === Mode::MODE_HTTP ? 1 : 0)`.
2. Boots the kernel.
3. Fetches `WorkerRegistryInterface` from the container.
4. Calls `$registry->getWorker($this->mode)`.
5. If no worker is found, logs `Missing RR worker implementation for <mode> mode` via `error_log()` and returns `1`.
6. Otherwise calls `$worker->start()` and returns `0`.
```

--------------------------------

### Inject MetricsInterface to record metrics

Source: https://github.com/baldinof/roadrunner-bundle/blob/3.x/README.md

Injects Spiral\RoadRunner\MetricsInterface into a controller and records a metric increment for 'user_login'. Returns a Response.

```php
class YouController
{
    public function index(MetricsInterface $metrics): Response
    {
        $metrics->add('user_login', 1);

        return new Response("...");
    }
}
```

--------------------------------

### Configure kernel_reboot with memory strategy

Source: https://github.com/baldinof/roadrunner-bundle/blob/3.x/README.md

Configuration to reboot the worker when memory usage exceeds a threshold. Default threshold is 128MB.

```yaml
# config/packages/baldinof_road_runner.yaml
baldinof_road_runner:
    kernel_reboot:
      strategy: memory
      memory_threshold_mb: 256 # memory threshold in megabytes (default: 128MB)
```

--------------------------------

### Catching BadConfigurationException when retrieving RPC service

Source: https://github.com/baldinof/roadrunner-bundle

Shows how to catch BadConfigurationException when fetching the RPC service from the container. The exception is thrown when the 'rpc' plugin is missing or has no address; the example includes a warning log and a comment with a sample .rr.yaml configuration.

```php
use Baldinof\RoadRunnerBundle\Exception\BadConfigurationException;

try {
    $rpc = $container->get(RPCInterface::class);
} catch (BadConfigurationException $e) {
    // "rpc" plugin is missing or has no address:
    // add a `rpc:` section to .rr.yaml, e.g.
    //   rpc:
    //     listen: tcp://127.0.0.1:6001
    $logger->warning($e->getMessage());
}
```

--------------------------------

### WorkerInterface PHP interface

Source: https://github.com/baldinof/roadrunner-bundle

Defines the single entry point for a worker. The start() method blocks until the worker stops.

```php
interface WorkerInterface
{
    public function start(): void;
}
```

--------------------------------

### XdebugProxy class skeleton

Source: https://github.com/baldinof/roadrunner-bundle

Thin proxy over the Xdebug extension so the bundle works without xdebug installed and the functions can be stubbed in tests. startWithRequest() reads xdebug.start_with_request (yes/no/trigger), falling back to 'yes' when profile mode is active, 'trigger' when debug or trace mode is active, else 'no'.

```php
class XdebugProxy
{
    public function isExtensionLoaded(): bool

    /**
     * @return 'yes'|'no'|'trigger'
     */
    public function startWithRequest(): string

    public function triggerValue(): ?string

    public function hasMode(string $mode): bool

    public function notify(mixed $data): bool

    public function connectToClient(): bool
}
```

--------------------------------

### Configure kernel_reboot with max_jobs strategy

Source: https://github.com/baldinof/roadrunner-bundle/blob/3.x/README.md

Configuration to reboot the worker every N requests to prevent memory leaks. max_jobs_dispersion adds randomness to avoid simultaneous reboots.

```yaml
# config/packages/baldinof_road_runner.yaml
baldinof_road_runner:
    kernel_reboot:
      strategy: max_jobs
      max_jobs: 1000 # maximum number of request
      max_jobs_dispersion: 0.2 # dispersion 20% used to prevent simultaneous reboot of all active workers (kernel will rebooted between 800 and 1000 requests)
```

--------------------------------

### Enable raw_body in RoadRunner

Source: https://github.com/baldinof/roadrunner-bundle/blob/3.x/README.md

Configuration to enable raw_body in RoadRunner's .rr.yaml. When enabled, $request->getContent() returns the original body, but multipart/form-data bodies are not parsed.

```yaml
# .rr.yaml
http:
  raw_body: true
```

--------------------------------

### DeclareMetricsListener class constructor

Source: https://github.com/baldinof/roadrunner-bundle

Defines the listener that declares collectors on the RoadRunner metrics plugin at worker start. The constructor injects the MetricsInterface service.

```php
final class DeclareMetricsListener implements EventSubscriberInterface
{
    public function __construct(private MetricsInterface $metrics)
    {
    }
}
```

--------------------------------

### Disable Default Integrations in YAML Configuration

Source: https://github.com/baldinof/roadrunner-bundle/blob/3.x/README.md

Use this YAML configuration to disable all default integrations (Sentry, Sessions, Doctrine, Blackfire, Xdebug) even though it is not recommended.

```yaml
baldinof_road_runner:
  default_integrations: false
```

--------------------------------

### Catching ExceptionInterface in application code

Source: https://github.com/baldinof/roadrunner-bundle

Example of catching any bundle exception using the ExceptionInterface marker. Place inside a try-catch block around application code that may trigger bundle errors.

```php
try {
    // application code
} catch (Baldinof\RoadRunnerBundle\Exception\ExceptionInterface $e) {
    // bundle-specific error
}
```

--------------------------------

### Typical full configuration (baldinof_road_runner.yaml)

Source: https://github.com/baldinof/roadrunner-bundle

Complete bundle configuration enabling default integrations, kernel reboot strategies, middlewares, interceptors, metrics, and KV storages. Adjust strategies, exceptions, and thresholds to your needs.

```yaml
# config/packages/baldinof_road_runner.yaml
baldinof_road_runner:
  default_integrations: true

  kernel_reboot:
    strategy: [on_exception, max_jobs, memory]
    allowed_exceptions:
      - Symfony\Component\HttpKernel\Exception\HttpExceptionInterface
      - App\Exception\YourDomainException
    max_jobs: 1000
    max_jobs_dispersion: 0.2
    memory_threshold_mb: 256

  middlewares:
    - App\Middleware\YourMiddleware
  interceptors:
    - App\Interceptor\YourInterceptor

  metrics:
    enabled: true
    collect:
      user_login:
        type: counter
        help: "Number of logged in user"

  kv:
    storages:
      - example

```

--------------------------------

### .rr.yaml production configuration template

Source: https://github.com/baldinof/roadrunner-bundle

Shipped with the bundle; copy with `cp vendor/baldinof/roadrunner-bundle/.rr.* .` when not using Flex. Sets APP_RUNTIME to the bundle's Runtime, enables static/gzip middleware, and includes commented-out rpc and metrics sections.

```yaml
version: "3"

server:
  command: "php public/index.php"
  env:
    - APP_RUNTIME: Baldinof\RoadRunnerBundle\Runtime\Runtime

http:
  address: 0.0.0.0:8080
  pool:
    debug: false
  middleware: [ "static", "gzip" ]
  uploads:
    forbid: [ ".php", ".exe", ".bat" ]
  static:
    dir: "public"
    forbid: [ ".php", ".htaccess" ]

logs:
  mode: production
  channels:
    http:
      level: debug # Log all http requests, set to info to disable
    server:
      level: info # Everything written to worker stderr is logged
      mode: raw
    metrics:
      level: error

# Uncomment to use metrics integration
# rpc:
#   listen: tcp://127.0.0.1:6001

# Uncomment to use metrics integration
# metrics:
#   # prometheus client address (path /metrics added automatically)
#   address: "0.0.0.0:9180"

```

--------------------------------

### build() method signature

Source: https://github.com/baldinof/roadrunner-bundle

The build() method registers compiler passes on the container. It is called during kernel boot and returns void.

```php
public function build(ContainerBuilder $container): void
```

--------------------------------

### Copy RoadRunner default configurations

Source: https://github.com/baldinof/roadrunner-bundle/blob/3.x/UPGRADE-2-0.md

Copy the default RoadRunner configuration files from the bundle to the project root.

```bash
# Copy RoadRunner default configurations
cp vendor/baldinof/roadrunner-bundle/.rr.* .
```

--------------------------------

### Service registration for cache.adapter.roadrunner.kv_<storage>

Source: https://github.com/baldinof/roadrunner-bundle

Registers a cache adapter service for each KV storage. Throws LogicException if required packages are missing.

```php
$container->register('cache.adapter.roadrunner.kv_'.$storage, KvCacheAdapter::class)
    ->setFactory([KvCacheAdapter::class, 'createConnection'])
    ->setArguments(['', [
        'rpc' => $container->getDefinition(RPCInterface::class),
        'storage' => $storage,
    ]]);
```

--------------------------------

### BaldinofRoadRunnerExtension::load() method signature

Source: https://github.com/baldinof/roadrunner-bundle

Signature of the load() method that processes configuration and wires the bundle into the container.

```php
public function load(array $configs, ContainerBuilder $container): void
```

--------------------------------

### addCollector()

Source: https://github.com/baldinof/roadrunner-bundle

Registers a collector definition with the metrics service. The collector is declared on the RoadRunner metrics plugin at worker start.

```APIDOC
## addCollector()

### Description
Registers a collector definition with the metrics service. The collector is declared on the RoadRunner metrics plugin at worker start.

### Method
addCollector

### Signature
`public function addCollector(string $name, array $definition): void`

### Parameters
- **$name** (non-empty-string) - Required - Collector name (e.g. `user_login`)
- **$definition** (array) - Required - Collector definition with keys: `type` (string, required), `buckets` (float[], optional), `help` (string, optional), `namespace` (string, optional), `subsystem` (string, optional), `labels` (non-empty-string[], optional)

### Behavior
- `type` must be one of `histogram`, `counter`, `gauge`, `summary` (values of `Spiral\RoadRunner\Metrics\CollectorType`). Anything else throws `\InvalidArgumentException` with message ``Metric type should be "gauge", "counter", "summary" or "histogram". "<type>" given``.
- `histogram` collectors are created with `Collector::histogram(...$definition['buckets'] ?? [])` — pass `buckets` to define bucket boundaries.
- Optional `help`, `namespace`, `subsystem`, `labels` are applied via the `withHelp()` / `withNamespace()` / `withSubsystem()` / `withLabels(...)` builder methods.
```

--------------------------------

### Configure Monolog channel for RoadRunner bundle

Source: https://github.com/baldinof/roadrunner-bundle

Configure the 'roadrunner' monolog channel to capture logs from the bundle's services. Place this in config/packages/monolog.yaml.

```yaml
# config/packages/monolog.yaml
monolog:
  channels: ['roadrunner']
  handlers:
    roadrunner:
      type: stream
      path: '%kernel.logs_dir%/roadrunner.log'
      level: debug
      channels: ['roadrunner']
```

--------------------------------

### Kernel reboot strategy configuration

Source: https://github.com/baldinof/roadrunner-bundle/blob/3.x/CHANGELOG.md

Configuration options for kernel reboot strategies, replacing the deprecated `should_reboot_kernel` option. Use `strategy: always` for equivalent behavior to `should_reboot_kernel: true`, or `strategy: on_exception` with `allowed_exceptions` to reboot only on selected exceptions.

```yaml
kernel_reboot:
  strategy: always # equivalent to `should_reboot_kernel: true`
```

```yaml
kernel_reboot:
  strategy: on_exception # equivalent to `should_reboot_kernel: false`
  allowed_exceptions:
    - Symfony\Component\HttpKernel\Exception\HttpExceptionInterface
```

--------------------------------

### withContext()

Source: https://github.com/baldinof/roadrunner-bundle

Returns a clone with the context replaced.

```APIDOC
## withContext()

### Description
Returns a clone with the context replaced.

### Method Signature
`public function withContext(ContextInterface $context): self`

### Parameters
- `$context` (ContextInterface) - Required - The new context

### Return Value
- `self` - Clone with replaced context
```

--------------------------------

### New configuration format for baldinof_road_runner

Source: https://github.com/baldinof/roadrunner-bundle/blob/3.x/UPGRADE-2-0.md

Migrate to the new configuration format for the baldinof_road_runner bundle. Includes kernel reboot strategy, allowed exceptions, metrics settings, and commented middleware configuration.

```yaml
# config/packages/baldinof_road_runner.yaml
baldinof_road_runner:
    # When the kernel should be rebooted.
    # See https://github.com/baldinof/roadrunner-bundle#kernel-reboots
    kernel_reboot:
        # if you want to use a fresh container on each request, use the `always` strategy
        strategy: on_exception
        # Exceptions you KNOW that do not put your app in an errored state
        allowed_exceptions:
           - Symfony\Component\HttpKernel\Exception\HttpExceptionInterface
           - Symfony\Component\Serializer\Exception\ExceptionInterface
           - Symfony\Contracts\HttpClient\Exception\ExceptionInterface

    # Allow to send prometheus metrics to the main RoadRunner process,
    # via a `Spiral\RoadRunner\MetricsInterface` service.
    # See https://github.com/baldinof/roadrunner-bundle#metrics
    metrics:
        enabled: false
        # collect:
        #     my_counter:
        #         type: counter
        #         help: Some help


    # You can use middlewares to manipulate Symfony requests & responses.
    # See https://github.com/baldinof/roadrunner-bundle#middlewares
    # middlewares:
    #     - App\Middleware\YourMiddleware
```

--------------------------------

### KvCacheAdapter class with createConnection method

Source: https://github.com/baldinof/roadrunner-bundle

Defines the KvCacheAdapter class extending Psr16Adapter. The createConnection method accepts a DSN (ignored) and options array containing 'rpc' and 'storage'.

```php
final class KvCacheAdapter extends Psr16Adapter
{
    public static function createConnection(#[[SensitiveParameter] string $dsn, array $options = []): self
}
```

--------------------------------

### WorkerStartEvent class definition

Source: https://github.com/baldinof/roadrunner-bundle

Base event class dispatched before the worker starts listening to requests. Extends Symfony's Event class. Not final, no properties or methods.

```php
class WorkerStartEvent extends Event
{
}
```

--------------------------------

### getService()

Source: https://github.com/baldinof/roadrunner-bundle

Returns the invoked service instance.

```APIDOC
## getService()

### Description
Returns the invoked service instance.

### Method Signature
`public function getService(): ServiceInterface`

### Return Value
- `ServiceInterface` - The invoked service
```

--------------------------------

### RoadRunner worker entry point configuration

Source: https://github.com/baldinof/roadrunner-bundle

Shows the .rr.yaml configuration and public/index.php entry point for the RoadRunner worker, setting APP_RUNTIME to the bundle's Runtime.

```yaml
# .rr.yaml
server:
  command: "php public/index.php"
  env:
    - APP_RUNTIME: Baldinof\RoadRunnerBundle\Runtime\Runtime
```

```php
<?php
// public/index.php
use App\Kernel;
use Baldinof\RoadRunnerBundle\Runtime\Runtime;

require_once dirname(__DIR__).'/vendor/autoload_runtime.php';

return function (array $context) {
    return new Kernel($context['APP_ENV'], (bool) $context['APP_DEBUG']);
};
```

--------------------------------

### RPCFactory::fromEnvironment method

Source: https://github.com/baldinof/roadrunner-bundle

Internal helper that reads the RR_RPC environment variable and creates an RPCInterface instance. Throws BadConfigurationException::rpcNotEnabled() if the variable is absent, and BadConfigurationException::missingRpcAddr() if the RPC address is missing.

```php
final class RPCFactory
{
    public static function fromEnvironment(EnvironmentInterface $environment): RPCInterface
}
```

--------------------------------

### getContext()

Source: https://github.com/baldinof/roadrunner-bundle

Returns the current context.

```APIDOC
## getContext()

### Description
Returns the current context.

### Method Signature
`public function getContext(): ContextInterface`

### Return Value
- `ContextInterface` - Current context
```

--------------------------------

### KvCacheAdapter::createConnection()

Source: https://github.com/baldinof/roadrunner-bundle

Creates a Symfony cache adapter for a RoadRunner KV storage. It reads the RPC interface and storage name from options, wraps the storage in a PSR-16 adapter, and returns the adapter instance.

```APIDOC
## KvCacheAdapter::createConnection()

### Description
Creates a Symfony cache adapter for a RoadRunner KV storage. It reads the RPC interface and storage name from options, wraps the storage in a PSR-16 adapter, and returns the adapter instance.

### Method
`createConnection` (static)

### Signature
```php
public static function createConnection(#[\SensitiveParameter] string $dsn, array $options = []): self
```

### Parameters
- **$dsn** (string) - Required - Ignored/overridden: Symfony replaces the first argument with the pool DSN, the bundle passes `''`.
- **$options** (array) - Required - Must contain `rpc` (a `Spiral\Goridge\RPC\RPCInterface`) and `storage` (the KV storage name).

### Return
`self` — a Symfony cache adapter usable as `cache.adapter.*` for framework cache pools.

### Behavior
1. Reads `$options['rpc']` as the `RPCInterface`.
2. Creates a `Spiral\RoadRunner\KeyValue\Factory` from it.
3. Selects `$options['storage']` via `Factory::select()`.
4. Wraps the storage in `new Psr16Adapter($storage)` and returns it.
```

--------------------------------

### ChainRebootStrategy PHP class implementation

Source: https://github.com/baldinof/roadrunner-bundle

Defines the ChainRebootStrategy class implementing KernelRebootStrategyInterface. It accepts an iterable of strategies via constructor injection. shouldReboot() returns true as soon as any wrapped strategy returns true (short-circuit), and clear() delegates to every wrapped strategy. Instantiated automatically by BaldinofRoadRunnerExtension when more than one strategy is configured.

```php
class ChainRebootStrategy implements KernelRebootStrategyInterface
{
    /**
     * @param iterable<KernelRebootStrategyInterface> $strategies
     */
    public function __construct(private iterable $strategies)
    {
    }
}
```

--------------------------------

### getMethod()

Source: https://github.com/baldinof/roadrunner-bundle

Returns the invoked method definition.

```APIDOC
## getMethod()

### Description
Returns the invoked method definition.

### Method Signature
`public function getMethod(): Method`

### Return Value
- `Method` - The invoked method
```

--------------------------------

### Runner::handle() method signature

Source: https://github.com/baldinof/roadrunner-bundle

Internal method that walks the middleware stack as an HttpKernelInterface. Delegates to the kernel handler when the stack is empty. Throws UnexpectedValueException if the first yield is not a Response.

```php
public function handle(Request $request, $type = self::MAIN_REQUEST, $catch = true): Response
```

--------------------------------

### Configuration for KV storages

Source: https://github.com/baldinof/roadrunner-bundle

YAML configuration for the bundle and RoadRunner side. The bundle config lists storages; the .rr.yaml defines the RPC and KV driver.

```yaml
# config/packages/baldinof_road_runner.yaml
baldinof_road_runner:
  kv:
    storages:
      - example
```

```yaml
# .rr.yaml
rpc:
  listen: tcp://127.0.0.1:6001

kv:
  example:
    driver: memory
    config: { }
```

--------------------------------

### Configuration for custom reboot strategy

Source: https://github.com/baldinof/roadrunner-bundle

YAML configuration that selects the custom strategy by its fully qualified class name. This is required to use the custom strategy.

```yaml
baldinof_road_runner:
  kernel_reboot:
    strategy: App\Reboot\EveryTenRebootStrategy
```

--------------------------------

### Generator-based middleware implementation

Source: https://github.com/baldinof/roadrunner-bundle

Shows an easy implementation using a generator. The first yield sends the response after setting a header; code after the yield runs in the termination phase after the response is sent.

```php
yield $next->handle($request)->headers->set('X-Middleware', 'MyMiddleware');
// code here runs after the response has been sent to the client
```

--------------------------------

### Catch BadConfigurationException when retrieving MetricsInterface

Source: https://github.com/baldinof/roadrunner-bundle

Wraps retrieval of `MetricsInterface` in a try-catch for `ExceptionInterface` to gracefully degrade when the RPC plugin is misconfigured or disabled.

```php
use Baldinof\RoadRunnerBundle\Exception\ExceptionInterface;
use Spiral\RoadRunner\Metrics\MetricsInterface;

try {
    $metrics = $container->get(MetricsInterface::class);
} catch (ExceptionInterface $e) {
    // metrics unavailable: log and degrade gracefully
}
```

--------------------------------

### OnExceptionRebootStrategy class skeleton

Source: https://github.com/baldinof/roadrunner-bundle

Defines the OnExceptionRebootStrategy class that implements KernelRebootStrategyInterface and EventSubscriberInterface. Constructor accepts an array of allowed exception class names and a logger for debug-level reboot decisions.

```php
class OnExceptionRebootStrategy implements KernelRebootStrategyInterface, EventSubscriberInterface
{
    public function __construct(array $allowedExceptions, LoggerInterface $logger)
}
```

--------------------------------

### Cache pool configuration and usage

Source: https://github.com/baldinof/roadrunner-bundle

Configures a Symfony cache pool using the RoadRunner adapter and demonstrates usage with a CacheInterface service.

```yaml
# config/packages/cache.yaml
framework:
  cache:
    pools:
      cache.example:
        adapter: cache.adapter.roadrunner.kv_example
```

```php
<?php

namespace App\Service;

use Symfony\Contracts\Cache\CacheInterface;

final class CachedStuff
{
    public function __construct(private CacheInterface $cache)
    {
    }

    public function compute(): string
    {
        return $this->cache->get('key', function (): string {
            return expensiveOperation();
        });
    }
}
```

--------------------------------

### withInput()

Source: https://github.com/baldinof/roadrunner-bundle

Returns a clone with the input replaced.

```APIDOC
## withInput()

### Description
Returns a clone with the input replaced.

### Method Signature
`public function withInput(?string $input): self`

### Parameters
- `$input` (?string) - Required - The new raw serialized input

### Return Value
- `self` - Clone with replaced input
```

--------------------------------

### Update RoadRunner binary

Source: https://github.com/baldinof/roadrunner-bundle/blob/3.x/UPGRADE-2-0.md

Update the RoadRunner binary to the latest version using the bundle's command.

```bash
vendor/bin/rr get-binary --location bin
```

--------------------------------

### Enable RoadRunner RPC plugin in .rr.yaml

Source: https://github.com/baldinof/roadrunner-bundle

Adds a `rpc:` section to the configuration file to enable the RoadRunner RPC plugin, required to avoid `BadConfigurationException::rpcNotEnabled()` when building services on `RPCInterface`.

```yaml
# .rr.yaml
rpc:
  listen: tcp://127.0.0.1:6001
```

--------------------------------

### MiddlewareCompilerPass class skeleton

Source: https://github.com/baldinof/roadrunner-bundle

Compiler pass that validates and pipes middleware services from the baldinof_road_runner.middlewares configuration. Throws LogicException, InvalidArgumentException, or InvalidArgumentException for missing service, missing class, or missing MiddlewareInterface respectively.

```php
class MiddlewareCompilerPass implements CompilerPassInterface
{
    public function process(ContainerBuilder $container): void
}
```

--------------------------------

### getInput()

Source: https://github.com/baldinof/roadrunner-bundle

Returns the raw serialized input message.

```APIDOC
## getInput()

### Description
Returns the raw serialized input message.

### Method Signature
`public function getInput(): ?string`

### Return Value
- `?string` - Raw serialized input
```

--------------------------------

### Runner::__construct()

Source: https://github.com/baldinof/roadrunner-bundle

Constructor for the Runner class, which initializes the kernel and mode for the RoadRunner worker.

```APIDOC
## Runner::__construct()

### Description
Constructor for the Runner class, which initializes the kernel and mode for the RoadRunner worker.

### Method
PHP constructor

### Endpoint
`Baldinof\RoadRunnerBundle\Runtime\Runner::__construct(KernelInterface $kernel, string $mode)`

### Parameters
- `$kernel` (Symfony\Component\HttpKernel\KernelInterface) - Required - The application kernel
- `$mode` (string) - Required - The RoadRunner worker mode; one of `Spiral\RoadRunner\Environment\Mode::MODE_HTTP` ("http") or `Mode::MODE_GRPC` ("grpc")
```

--------------------------------

### MiddlewareStack class implementation

Source: https://github.com/baldinof/roadrunner-bundle

Internal class implementing RequestHandlerInterface. handle() clones the middleware stack into a Runner, yields the response, then closes iterators for termination. pipe() pushes middleware in LIFO order for the compiler pass.

```php
final class MiddlewareStack implements RequestHandlerInterface
{
    public function __construct(
        private RequestHandlerInterface $kernelHandler,
        private \SplStack $middlewares = new \SplStack(),
    ) {
    }

    public function handle(Request $request): \Iterator

    public function pipe(MiddlewareInterface $middleware): void
}
```

--------------------------------

### GrpcServiceCompilerPass class skeleton

Source: https://github.com/baldinof/roadrunner-bundle

Compiler pass that finds services tagged baldinof.roadrunner.grpc_service, inspects implemented interfaces via class_implements(), keeps subclasses of Spiral\RoadRunner\GRPC\ServiceInterface, and adds registerService() calls to the GrpcServiceProvider definition.

```php
class GrpcServiceCompilerPass implements CompilerPassInterface
{
    public function process(ContainerBuilder $container): void
}
```

--------------------------------

### WorkerInterface and WorkerRegistryInterface definitions

Source: https://github.com/baldinof/roadrunner-bundle

Defines the worker lifecycle and a mode-keyed registry. `WorkerInterface::start()` blocks until the worker stops. `WorkerRegistryInterface::registerWorker()` stores a worker under a mode string (e.g. `'http'` or `'grpc'`); `getWorker()` returns `null` for unregistered modes. Used by `Runtime\Runner` and `WorkerRegistry`.

```php
interface WorkerInterface
{
    public function start(): void;
}

interface WorkerRegistryInterface
{
    public function registerWorker(string $mode, WorkerInterface $worker): void;

    public function getWorker(string $mode): ?WorkerInterface;
}
```

--------------------------------

### Runner constructor

Source: https://github.com/baldinof/roadrunner-bundle

Constructor for Runner that accepts a KernelInterface and a mode string (http or grpc).

```php
public function __construct(
    private KernelInterface $kernel,
    private string $mode)
{
}
```

--------------------------------

### BadConfigurationException class definition

Source: https://github.com/baldinof/roadrunner-bundle

Final exception class extending \RuntimeException and implementing ExceptionInterface. Provides static factory methods rpcNotEnabled() and missingRpcAddr() for RPC configuration failures.

```php
final class BadConfigurationException extends \RuntimeException implements ExceptionInterface
{
    public static function rpcNotEnabled(): self

    public static function missingRpcAddr(): self
}
```

--------------------------------

### withContextValue()

Source: https://github.com/baldinof/roadrunner-bundle

Returns a clone with a context value applied.

```APIDOC
## withContextValue()

### Description
Returns a clone with `$context->withValue($key, $value)` applied.

### Method Signature
`public function withContextValue(string $key, mixed $value): self`

### Parameters
- `$key` (string) - Required - Must be a non-empty string
- `$value` (mixed) - Required - The value to set

### Return Value
- `self` - Clone with the context value applied
```

--------------------------------

### Runner::run() method signature

Source: https://github.com/baldinof/roadrunner-bundle

Defines the run method that returns an int status code.

```php
public function run(): int
```

--------------------------------

### declareMetrics() method signature

Source: https://github.com/baldinof/roadrunner-bundle

Declares every registered collector with $this->metrics->declare($name, $collector).

```php
public function declareMetrics(WorkerStartEvent $event): void
```

--------------------------------

### MiddlewareInterface process method signature

Source: https://github.com/baldinof/roadrunner-bundle

Defines the contract for HTTP middlewares. The process method receives a Request and the next HttpKernelInterface, returning an Iterator. Only the first yielded item is sent to the client; subsequent yields run after the response is sent.

```php
interface MiddlewareInterface
{
    public function process(Request $request, HttpKernelInterface $next): \Iterator;
}
```

--------------------------------

### AlwaysRebootStrategy class skeleton

Source: https://github.com/baldinof/roadrunner-bundle

Defines the AlwaysRebootStrategy class that implements KernelRebootStrategyInterface. shouldReboot() always returns true, forcing a fresh container on every request. Configuration strategy key: 'always'.

```php
class AlwaysRebootStrategy implements KernelRebootStrategyInterface
{
    public function shouldReboot(): bool

    public function clear(): void
}
```

--------------------------------

### Metrics configuration YAML

Source: https://github.com/baldinof/roadrunner-bundle

Enables metrics and defines collectors. The collect node maps collector names to definitions; histogram buckets are optional.

```yaml
# config/packages/baldinof_road_runner.yaml
baldinof_road_runner:
  metrics:
    enabled: true
    collect:
      user_login:
        type: counter
        help: "Number of logged in user"
      request_duration:
        type: histogram
        buckets: [0.1, 0.25, 0.5, 1.0]
```

--------------------------------

### Copy RoadRunner config files

Source: https://github.com/baldinof/roadrunner-bundle/blob/3.x/UPGRADE-3-0.md

Copy the RoadRunner configuration files from the bundle to the project root when upgrading to version 3.x, which supports RoadRunner 2023.x.

```bash
cp vendor/baldinof/roadrunner-bundle/.rr.* .
```

--------------------------------

### Bundle class declaration

Source: https://github.com/baldinof/roadrunner-bundle

The bundle entry point class, final and extending Symfony's Bundle. It is registered in the kernel when Symfony Flex is not used.

```php
final class BaldinofRoadRunnerBundle extends Bundle
```

--------------------------------

### OnExceptionRebootStrategy event subscriptions

Source: https://github.com/baldinof/roadrunner-bundle

Subscribes to KernelEvents::EXCEPTION and ForceKernelRebootEvent. The onException method records throwables only for MAIN_REQUEST, while onForceKernelReboot records forced reboot requests from DoctrineORMMiddleware or user code.

```php
public static function getSubscribedEvents(): array
{
    return [
        KernelEvents::EXCEPTION => 'onException',
        ForceKernelRebootEvent::class => 'onForceKernelReboot',
    ];
}
```
Tokens:
Raw