### Install RoadRunner Library

Source: https://github.com/roadrunner-server/docs/blob/master/customization/embedding.md

Use 'go get' to add the RoadRunner library to your Go project.

```bash
go get -u github.com/roadrunner-server/roadrunner/v2025/lib
```

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

### Install Velox using Go

Source: https://github.com/roadrunner-server/docs/blob/master/customization/build.md

Install the Velox binary using the `go install` command. Requires Golang 1.22+.

```bash
go install github.com/roadrunner-server/velox/v2025/cmd/vx@latest
```

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

### Basic Temporal Worker Setup

Source: https://github.com/roadrunner-server/docs/blob/master/workflow/worker.md

Configure and run a basic Temporal worker. This snippet shows how to create a worker factory, register workflow and activity types, and start the worker's primary loop.

```php
<?php

declare(strict_types=1);

use Temporal\WorkerFactory;

ini_set('display_errors', 'stderr');
include "vendor/autoload.php";

// factory initiates and runs task queue specific activity and workflow workers
$factory = WorkerFactory::create();

// Worker that listens on a task queue and hosts both workflow and activity implementations.
$worker = $factory->newWorker(
    'taskQueue',
    \Temporal\Worker\WorkerOptions::new()->withMaxConcurrentActivityExecutionSize(10)
);

// Workflows are stateful. So you need a type to create instances.
$worker->registerWorkflowTypes(MyWorkflow::class);

// Activities are stateless and thread safe. So a shared instance is used.
$worker->registerActivityImplementations(new MyActivity());


// start primary loop
$factory->run();

```

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

### Install Goridge via Composer

Source: https://github.com/roadrunner-server/docs/blob/master/php/rpc.md

Install the Goridge library using Composer. This is the first step to enable RPC communication.

```bash
composer require spiral/goridge
```

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

### Example .rr.yaml Configuration

Source: https://github.com/roadrunner-server/docs/blob/master/CLAUDE.md

This is an example of a .rr.yaml configuration file. It is used to define the server's behavior and plugins.

```yaml
server:
  command: "/usr/bin/php"
  relay: "pipes"
  supervisor: "pipes"

http:
  address: "127.0.0.1:8080"
  middleware:
    - "gzip"

plugins:
  http: true
  grpc: true
  jobs: true
  kv: true

jobs:
  num_processes: 2
  supervisor:
    - name: "worker"
      command: "php artisan queue:listen --tries=3"
      relay: "pipes"
      supervisor:
        - name: "listener"
          command: "php artisan queue:listen --tries=3"
          relay: "pipes"

kv:
  redis:
    - address: "localhost:6379"

```

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

### Example RoadRunner Startup Logs

Source: https://github.com/roadrunner-server/docs/blob/master/lab/logger.md

These are example logs emitted directly by the RoadRunner core during startup. They are not controlled by the main logs configuration.

```log
[INFO] RoadRunner server started; version: 2024.3.0, buildtime: 2024-12-05T18:39:32+0000
[INFO] sdnotify: not notified
```

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

### Install RoadRunner Service Plugin

Source: https://github.com/roadrunner-server/docs/blob/master/plugins/service.md

Install the RoadRunner Service Plugin PHP client library using Composer.

```bash
composer require spiral/roadrunner-services
```

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

### Install Temporal PHP SDK

Source: https://github.com/roadrunner-server/docs/blob/master/workflow/worker.md

Install the Temporal PHP SDK using Composer. This is a prerequisite for setting up a Temporal worker.

```bash
$ composer require temporal/sdk
```

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

### Included Configuration File Example

Source: https://github.com/roadrunner-server/docs/blob/master/intro/config.md

This is an example of an included configuration file. Its settings for 'server' and 'http' will override those in the main configuration file.

```yaml
version: "3"

server:
  command: "php php_test_files/psr-worker-bench.php"
  relay: pipes

http:
  address: 127.0.0.1:15389
  middleware:
    - "sendfile"
  pool:
    allocate_timeout: 10s
    num_workers: 2
```

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

### Server Plugin Configuration Example

Source: https://github.com/roadrunner-server/docs/blob/master/plugins/server.md

This example demonstrates the configuration for the server plugin in a .rr.yaml file. It includes settings for initialization commands, worker startup, user/group, environment variables, and the relay type.

```yaml
server:
  on_init:
    # Command to execute before the main server's command
    #
    # This option is required if using on_init
    command: "any php or script here"

    # Username (not UID) of the user from whom the on_init command is executed. An empty value means to use the RR process user.
    #
    # Default: ""
    user: ""

    # Script execute timeout
    #
    # Default: 60s [60m, 60h], if used w/o units its means - NANOSECONDS.
    exec_timeout: 20s

    # Environment variables for the worker processes.
    #
    # Default: <empty map>
    env:
      - SOME_KEY: "SOME_VALUE"
      - SOME_KEY2: "SOME_VALUE2"

    # Exit RR if the `on_init` command fails or exceeds the `exec_timeout`.
    exit_on_error: false

  # Worker starting command, with any required arguments.
  #
  # This option is required.
  command: "php psr-worker.php"

  # Username (not UID) for the worker processes. An empty value means to use the RR process user.
  #
  # Default: ""
  user: ""

  # Group name (not GID) for the worker processes. An empty value means to use the RR process user.
  #
  # Default: ""
  group: ""

  # Environment variables for the worker processes.
  #
  # Default: <empty map>
  env:
    - SOME_KEY: "SOME_VALUE"
    - SOME_KEY2: "SOME_VALUE2"

  relay: pipes
```

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

### Plugin Dependencies Example

Source: https://github.com/roadrunner-server/docs/blob/master/customization/plugin.md

Demonstrates how to declare and initialize dependencies for a custom plugin using interfaces.

```go
package custom

import (
    "go.uber.org/zap"
)

type Configurer interface { // <-- config plugin implements
    // UnmarshalKey takes a single key and unmarshal it into a Struct.
    UnmarshalKey(name string, out any) error
    // Has checks if config section exists.
    Has(name string) bool
}

type Logger interface { // <-- logger plugin implements
    NamedLogger(name string) *zap.Logger
}

type Service struct{}

func (s *Service) Init(r Configurer, log Logger) error {
    return nil
}
```

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

### systemd Unit File for RoadRunner

Source: https://github.com/roadrunner-server/docs/blob/master/app-server/systemd.md

This is an example systemd unit file to run RoadRunner as a daemon. Ensure paths to the binary and configuration file are correct for your setup.

```ini
[Unit]
Description=High-performance PHP application server
Documentation=https://docs.roadrunner.dev/

[Service]
ExecStart=/usr/local/bin/rr serve -c /var/www/.rr.yaml

Type=notify

# Prevent systemd from terminating the worker processes
KillMode=mixed

# Adjust this to the value in jobs.pool.destroy_timeout
TimeoutStopSec=30

Restart=always
RestartSec=30

[Install]
WantedBy=default.target
```

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

### Release Note Format Example

Source: https://github.com/roadrunner-server/docs/blob/master/CLAUDE.md

This example shows the format for release notes, including versioning, plugin sections, and entry types (feature, bug fix).

```markdown
# 🚀 v2025-1-10 🚀

### 📦 `http` plugin

✨ Add new feature to http plugin.

### 🎯 Core

🐛 Fix bug in core functionality.

[FR] Add support for new protocol.
[BUG] Resolve issue with configuration loading.

```

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

### Start RoadRunner Server with Custom Config

Source: https://github.com/roadrunner-server/docs/blob/master/app-server/cli.md

Starts the server specifying a custom configuration file path using the -c option.

```terminal
./rr serve -c /var/www/.rr.yaml
```

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

### Example Trace Headers

Source: https://github.com/roadrunner-server/docs/blob/master/grpc/grpc.md

Example of Traceparent and Uber-Trace-Id headers passed to PHP workers when OTLP is enabled.

```log
"Traceparent":["00-2678b910f57fe3320587f4126a390868-6b87f1600005b643-01"],"Uber-Trace-Id":["2678b910f57fe3320587f4126a390868:6b87f1600005b643:0:1"]
```

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

### PHP Subscription Workflow Example

Source: https://github.com/roadrunner-server/docs/blob/master/workflow/temporal.md

An example of a Temporal workflow in PHP that manages a subscription, including sending welcome emails, charging monthly fees, and handling cancellations.

```php
class SubscriptionWorkflow implements SubscriptionWorkflowInterface
{
    private $account;

    public function __construct()
    {
        $this->account = Workflow::newActivityStub(
            AccountActivityInterface::class,
            ActivityOptions::new()
                ->withScheduleToCloseTimeout(DateInterval::createFromDateString('2 seconds'))
        );
    }

    public function subscribe(string $userID)
    {
        yield $this->account->sendWelcomeEmail($userID);

        try {
            $trialPeriod = true;
            while (true) {
                // Lower period duration to observe workflow behavior
                yield Workflow::timer(DateInterval::createFromDateString('30 days'));
                yield $this->account->chargeMonthlyFee($userID);

                if ($trialPeriod) {
                    yield $this->account->sendEndOfTrialEmail($userID);
                    $trialPeriod = false;
                    continue;
                }

                yield $this->account->sendMonthlyChargeEmail($userID);
            }
        } catch (CanceledFailure $e) {
            yield Workflow::asyncDetached(
                function () use ($userID) {
                    yield $this->account->processSubscriptionCancellation($userID);
                    yield $this->account->sendSorryToSeeYouGoEmail($userID);
                }
            );
        }
    }
}
```

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

### Start Embedded RoadRunner Server

Source: https://github.com/roadrunner-server/docs/blob/master/customization/embedding.md

Start the embedded RoadRunner server in a goroutine and capture potential errors.

```go
errCh := make(chan error, 1)
go func() {
    errCh <- rr.Serve()
}()
```

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

### Usage Example for AsyncCache

Source: https://github.com/roadrunner-server/docs/blob/master/php/rpc.md

This example shows how to instantiate and use the AsyncCache class to perform multiple asynchronous set operations and then commit them.

```php
$cache = new AsyncCache($rpc);

$cache->setAsync('key', ['foo' => 'bar']);
$cache->setAsync('second', ['key' => 'value']);
$cache->setAsync('third', 'data');

$result = $cache->commitAsync();

```

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

### Install RoadRunner TCP Package

Source: https://github.com/roadrunner-server/docs/blob/master/plugins/tcp.md

Install the RoadRunner TCP PHP package using Composer.

```bash
composer require spiral/roadrunner-tcp
```

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

### Example .rr.yaml Service Configuration

Source: https://github.com/roadrunner-server/docs/blob/master/plugins/service.md

This is an example of a `.rr.yaml` file demonstrating the configuration for multiple services, including MeiliSearch, Centrifuge, and a custom PHP service. It shows how to define commands, process numbers, timeouts, restart policies, environment variables, and user permissions for each service.

```yaml
version: "3"

service:
  meilisearch:
    service_name_in_log: true
    timeout_stop_sec: 10
    remain_after_exit: true
    restart_sec: 1
    command: "./bin/meilisearch"
    user: "www-data"
  centrifuge:
    service_name_in_log: true
    timeout_stop_sec: 10
    remain_after_exit: true
    restart_sec: 1
    command: "./bin/centrifugo --config=centrifugo.json"
  some_service_1:
    command: "php loop.php"
    process_num: 10
    timeout_stop_sec: 10
    exec_timeout: 0s
    remain_after_exit: true
    service_name_in_log: false
    env:
      - foo: "BAR"
    restart_sec: 1

```

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

### Start RoadRunner Server with Custom Working Directory

Source: https://github.com/roadrunner-server/docs/blob/master/app-server/cli.md

Starts the server specifying a custom working directory using the -w option.

```terminal
./rr serve -w /var/www
```

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

### Start RoadRunner Server

Source: https://github.com/roadrunner-server/docs/blob/master/intro/quick-start.md

Command to start the RoadRunner server. Ensure you have the 'rr' binary, '.rr.yaml', and 'psr-worker.php' in the current directory.

```bash
./rr serve
```

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

### Install RoadRunner with cURL

Source: https://github.com/roadrunner-server/docs/blob/master/intro/install.md

Quickly install the latest RoadRunner binary using cURL and a shell script from the official GitHub repository.

```bash
curl --proto '=https' --tlsv1.2 -sSf  https://raw.githubusercontent.com/roadrunner-server/roadrunner/master/download-latest.sh | sh
```

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

### Install igbinary extension

Source: https://github.com/roadrunner-server/docs/blob/master/kv/overview-kv.md

Command to install the igbinary extension on Linux and macOS systems. This extension improves serialization performance.

```bash
pecl install igbinary
```

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

### PHP Example: Calling the MGet RPC method

Source: https://github.com/roadrunner-server/docs/blob/master/kv/overview-kv.md

Example of how to connect to the RoadRunner RPC server and call the MGet method using protobuf encoding.

```php
use Spiral\Goridge\RPC\RPC;
use Spiral\Goridge\RPC\Codec\ProtobufCodec;
use RoadRunner\KV\DTO\V1\{Request, Response};

$response = RPC::create('tcp://127.0.0.1:6001')
    ->withServicePrefix('kv')
    ->withCodec(new ProtobufCodec())
    ->call('MGet', new Request([ ... ]), Response::class);
```

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

### Start RoadRunner Server with Dotenv

Source: https://github.com/roadrunner-server/docs/blob/master/app-server/cli.md

Starts the server and loads environment variables from a .env file using the --dotenv option, along with a specified configuration file.

```terminal
./rr serve --dotenv .env -c .rr.yaml
```

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

### Redis Driver Configuration Example

Source: https://github.com/roadrunner-server/docs/blob/master/kv/redis.md

Configure the Redis driver for a single connection to a Redis server. This example shows all available configuration options, including addresses, authentication, database selection, timeouts, connection pooling, and TLS settings.

```yaml
version: "3"

kv:
  # User defined name of the storage.
  redis:
    # Required section.
    # Should be "redis" for the redis driver.
    driver: redis

    config:
      # Optional section.
      # By default, one connection will be specified with the "127.0.0.1:6379" value.
      addrs:
        - "127.0.0.1:6379"

      # Optional section.
      # Default: ""
      username: ""

      # Optional section.
      # Default: ""
      password: ""

      # Optional section.
      # Default: 0
      db: 0

      # Optional section.
      # Default: 0 (equivalent to the default value of 5 seconds)
      dial_timeout: 0

      # Optional section.
      # Default: 0 (equivalent to the default value of 3 retries)
      max_retries: 0

      # Optional section.
      # Default: 0 (equivalent to the default value of 8ms)
      min_retry_backoff: 0

      # Optional section.
      # Default: 0 (equivalent to the default value of 512ms)
      max_retry_backoff: 0

      # Optional section.
      # Default: 0 (equivalent to the default value of 10 connections per CPU).
      pool_size: 0

      # Optional section.
      # Default: 0 (do not use idle connections)
      min_idle_conns: 0

      # Optional section.
      # Default: 0 (do not close aged connections)
      max_conn_age: 0

      # Optional section.
      # Default: 0 (equivalent to the default value of 3s)
      read_timeout: 0

      # Optional section.
      # Default: 0 (equivalent to the value specified in the "read_timeout" section)
      write_timeout: 0

      # Optional section.
      # Default: 0 (equivalent to the value specified in the "read_timeout" + 1s)
      pool_timeout: 0

      # Optional section.
      # Default: 0 (equivalent to the default value of 5m)
      idle_timeout: 0

      # Optional section.
      # Default: 0 (equivalent to the default value of 1m)
      idle_check_freq: 0

      # Optional section.
      # Default: false
      read_only: false

      # Optional section.
      tls:
        # Optional section.
        # Default: ""
        cert: ""

        # Optional section.
        # Default: ""
        key: ""

        # Optional section.
        # Default: ""
        root_ca: ""

```

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

### Initialize Key-Value Factory with Igbinary Serializer

Source: https://github.com/roadrunner-server/docs/blob/master/kv/overview-kv.md

Example of creating a Key-Value factory that uses the igbinary serializer for faster serialization and deserialization.

```php
use Spiral\Goridge\RPC\RPC;
use Spiral\RoadRunner\KeyValue\Factory;
use Spiral\RoadRunner\KeyValue\Serializer\IgbinarySerializer;

$storage = (new Factory($rpc)
    ->withSerializer(new IgbinarySerializer())
    ->select('storage');
```

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

### HTTP Plugin Configuration Example

Source: https://github.com/roadrunner-server/docs/blob/master/http/http.md

Example configuration for the HTTP plugin in .rr.yaml, specifying the listening address, internal error code, access logs, max request size, raw body handling, middleware, trusted subnets, and file upload settings.

```yaml
version: "3"

# HTTP plugin settings.
http:
  # Host and port to listen on (e.g.: `127.0.0.1:8080`).
  #
  # This option is required.
  address: 127.0.0.1:8080

  # Override HTTP error code for internal RR errors
  #
  # Default: 500
  internal_error_code: 505

  # HTTP access logs
  #
  # Default: false
  access_logs: false

  # Maximum incoming request size in megabytes. Zero means no limit.
  #
  # Default: 0
  max_request_size: 256

  # Send raw body (unescaped) to the PHP worker for the application/x-www-form-urlencoded content type
  #
  # Optional, default: false
  raw_body: false

  # Middleware for the HTTP plugin; order is important. Allowed values are: "headers", "gzip", "static", "sendfile", [SINCE 2.6] -> "new_relic", [SINCE 2.6] -> "http_metrics", [SINCE 2.7] -> "cache"
  #
  # Default value: []
  middleware: [ "headers", "gzip" ]

  # Allow incoming requests only from the following subnets (https://en.wikipedia.org/wiki/Reserved_IP_addresses).
  #
  # Default: ["10.0.0.0/8", "127.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16",  "::1/128", "fc00::/7", "fe80::/10"]
  trusted_subnets: [
    "10.0.0.0/8",
    "127.0.0.0/8",
    "172.16.0.0/12",
    "192.168.0.0/16",
    "::1/128",
    "fc00::/7",
    "fe80::/10",
  ]

  # File uploading settings.
  uploads:
    # Directory for file uploads. Empty value means to use $TEMP based on your OS.
    #
    # Default: ""
    dir: "/tmp"

    # Deny files with the following extensions to upload.
    #
    # Default: [ ".php", ".exe", ".bat" ]
    forbid: [ ".php", ".exe", ".bat", ".sh" ]

    # [SINCE 2.6] Allow files with the following extensions to upload
    #
    # Default: empty
    allow: [ ".html", ".aaa" ]

```

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

### Install PSR-15 Dependency

Source: https://github.com/roadrunner-server/docs/blob/master/integration/migration.md

Explicitly declare and install a PSR-15 implementation using Composer. This example uses nyholm/psr7.

```bash
$ composer require nyholm/psr7
```

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

### AMQP Connection Configuration

Source: https://github.com/roadrunner-server/docs/blob/master/queues/amqp.md

Configure the AMQP connection address. This example shows a basic connection to a RabbitMQ instance.

```yaml
amqp:
  addr: amqp://guest:guest@127.0.0.1:5672
```

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

### Proto Path Configuration Example

Source: https://github.com/roadrunner-server/docs/blob/master/grpc/protoreg.md

Define a list of directories where the plugin should search for proto files and their dependencies, similar to protoc's -I flag.

```yaml
proto_path:
  - proto/commonapis     # Shared message definitions
  - proto/serviceapis    # Service-specific proto definitions
  - proto/third_party    # External dependencies (e.g., google/api)
```

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

### Commit Message Style Examples

Source: https://github.com/roadrunner-server/docs/blob/master/CLAUDE.md

Examples of commit messages following the specified style guide, including chore, fix, and issue-linked commits.

```text
chore: update documentation for release v2025-1-10

```

```text
fix: resolve issue with job processing

```

```text
[#123]: implement new user authentication

```

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

### Enable Experimental Features (Short Flag)

Source: https://github.com/roadrunner-server/docs/blob/master/experimental/experimental.md

Use the -e flag to enable experimental features when starting the Roadrunner server.

```bash
./rr serve -e
```

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

### Custom Plugin Initialization

Source: https://github.com/roadrunner-server/docs/blob/master/customization/plugin.md

Shows how to initialize a custom plugin, including configuration unmarshalling and default value handling.

```go
package custom

import (
    "go.uber.org/zap"
    "github.com/roadrunner-server/errors"
)

const PluginName = "custom"

type Configurer interface { // <-- config plugin implements
    // UnmarshalKey takes a single key and unmarshal it into a Struct.
    UnmarshalKey(name string, out any) error
    // Has checks if config section exists.
    Has(name string) bool
}

type Logger interface { // <-- logger plugin implements
    NamedLogger(name string) *zap.Logger
}

type Plugin struct {
    cfg *Config
}

// Init plugin
// file: plugin.go
func (s *Plugin) Init(cfg Configurer, log Logger) error {
    const op = errors.Op("custom_plugin_init") // error operation name
    if !cfg.Has(PluginName) {
        return errors.E(op, errors.Disabled)
    }

    // unmarshal initial configuration
    err := cfg.UnmarshalKey(PluginName, &s.cfg)
    if err != nil {
        // Error will stop execution
        return errors.E(op, err)
    }

    // Check the unmarshaled configuration and fill in defaults if not provided by the configuration
    s.cfg.InitDefaults()

    return nil
}
```

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

### Custom Plugin Initialization with Protoreg Registry

Source: https://github.com/roadrunner-server/docs/blob/master/grpc/protoreg.md

Demonstrates how a custom Go plugin can initialize and interact with the protoreg registry. It shows how to access the underlying registry, retrieve all registered services, and find specific methods by their full path.

```go
package myplugin

import (
	"github.com/jhump/protoreflect/desc"
	"github.com/jhump/protoreflect/v2/protoresolve"
)

type Registry interface {
    Registry() *protoresolve.Registry
    Services() map[string]*desc.ServiceDescriptor
    FindMethodByFullPath(method string) (*desc.MethodDescriptor, error)
}

type Plugin struct {
    registry Registry
}

func (p *Plugin) Init(registry Registry) error {

    p.registry = registry

    // Access the underlying registry
    reg := p.registry.Registry()

    // Get all registered services
    services := p.registry.Services()

    // Find a specific method by its full path
    method, err := p.registry.FindMethodByFullPath("/service.v1.MyService/Process")
    if err != nil {
        return err
    }

    // Use the method descriptor for reflection
    inputType := method.GetInputType()
    outputType := method.GetOutputType()

    return nil
}
```

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

### Simple PHP Worker Example

Source: https://github.com/roadrunner-server/docs/blob/master/plugins/server.md

This worker waits for incoming payloads, processes them, and sends a 'DONE' response back to the server. Ensure you have the RoadRunner client package installed via Composer.

```php
<?php

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

// Create a new Worker from global environment
$worker = \Spiral\RoadRunner\Worker::create();

while ($data = $worker->waitPayload()) {
    // Received Payload
    var_dump($data);

    // Respond Answer
    $worker->respond(new \Spiral\RoadRunner\Payload('DONE'));
}

```

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

### Build Application Server with vx

Source: https://github.com/roadrunner-server/docs/blob/master/customization/build.md

Build the application server using the `vx build` command. Specify the configuration path with -c and the output path with -o. Requires Golang 1.22+.

```bash
vx build -c velox.toml -o ~/Downloads
```

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

### Install RoadRunner with Chocolatey

Source: https://github.com/roadrunner-server/docs/blob/master/intro/install.md

Install RoadRunner on Windows using the Chocolatey package manager.

```powershell
choco install roadrunner
```

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

### Files Configuration Example

Source: https://github.com/roadrunner-server/docs/blob/master/grpc/protoreg.md

Specify the proto files to be parsed and registered. Paths are relative to the proto_path directories, similar to protoc's variadic file arguments.

```yaml
files:
  - service/v1/service.proto    # Your gRPC service definitions
  - user/v1/user.proto          # Additional service definitions
```

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

### Install RoadRunner with Homebrew

Source: https://github.com/roadrunner-server/docs/blob/master/intro/install.md

Install RoadRunner on macOS using the Homebrew package manager.

```bash
brew install roadrunner
```

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

### Start RoadRunner systemd Service

Source: https://github.com/roadrunner-server/docs/blob/master/app-server/systemd.md

Command to start the RoadRunner systemd user service.

```bash
systemctl start rr.service
```

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

### Project Structure Example

Source: https://github.com/roadrunner-server/docs/blob/master/grpc/protoreg.md

Illustrates a typical project layout for projects utilizing the protoreg plugin, including directories for proto definitions and configuration files.

```tree
my-project/
├── .rr.yaml
├── proto/
│   ├── commonapis/
│   │   └── common/
│   │       └── v1/
│   │           └── message.proto
│   └── serviceapis/
│       └── service/
│           └── v1/
│               └── service.proto
└── ...
```

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

### Install RoadRunner Jobs PHP Dependency

Source: https://github.com/roadrunner-server/docs/blob/master/queues/overview-queues.md

Install the RoadRunner Jobs PHP dependency using Composer.

```bash
composer require spiral/roadrunner-jobs
```

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

### Subscribe with Wildcard Pattern - Go

Source: https://github.com/roadrunner-server/docs/blob/master/customization/events-bus.md

This example shows how to subscribe to events using a wildcard pattern, such as `http.*`, to match any event originating from the HTTP plugin. It also demonstrates sending and receiving an event.

```go
package foo

import (
    "github.com/roadrunner-server/events"
)

func foo() {
    eh, id := events.Bus()
    defer eh.Unsubscribe(id)

    ch := make(chan events.Event, 100)

    // Subscribe to the events which fits your pattern (`http.*`).
    err := eh.SubscribeP(id, "http.*", ch)
    if err != nil {
        panic(err)
    }

    eh.Send(events.NewEvent(events.EventJobOK, "http", "foo"))
    evt := <-ch
    // evt.Message() -> "foo"
    // evt.Plugin() -> "http"
    // evt.Type().String() -> "EventJobOK"
}
```

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

### Install Symfony Lock Driver

Source: https://github.com/roadrunner-server/docs/blob/master/plugins/locks.md

Install the RoadRunner Symfony Lock driver package using Composer.

```bash
composer require roadrunner-php/symfony-lock-driver
```

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

### Install RoadRunner Lock PHP Package

Source: https://github.com/roadrunner-server/docs/blob/master/plugins/locks.md

Install the PHP package for the RoadRunner lock plugin using Composer.

```bash
composer require roadrunner-php/lock
```

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

### Install RoadRunner CLI via Composer

Source: https://github.com/roadrunner-server/docs/blob/master/grpc/grpc.md

Installs the spiral/roadrunner-cli package using Composer to manage PHP dependencies.

```bash
composer require spiral/roadrunner-cli
```

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

### Example YAML Configuration File

Source: https://github.com/roadrunner-server/docs/blob/master/plugins/config.md

Demonstrates the basic structure of a RoadRunner YAML configuration file, including the required version field.

```yaml
version: '3'

# ... other config values

```

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

### YAML Configuration Sample

Source: https://github.com/roadrunner-server/docs/blob/master/customization/plugin.md

A sample YAML configuration file for a custom plugin.

```yaml
custom:
  address: tcp://127.0.0.1:8888
```

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

### Install RoadRunner gRPC PHP Package

Source: https://github.com/roadrunner-server/docs/blob/master/grpc/grpc.md

Install the necessary PHP package via Composer to enable gRPC functionality.

```bash
composer require spiral/roadrunner-grpc
```

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

### Select and Use Key-Value Storage

Source: https://github.com/roadrunner-server/docs/blob/master/kv/overview-kv.md

Creates a KeyValue factory using an existing RPC connection and selects a storage driver. It demonstrates basic cache operations like setting and getting a key.

```php
use Spiral\Goridge\RPC\RPC;
use Spiral\RoadRunner\KeyValue\Factory;

$factory = new Factory($rpc);

$storage = $factory->select('storage-name');

// Expected:
//  An instance of Psr\SimpleCache\CacheInterface interface

$storage->set('key', 'value');

var_dump($storage->get('key'));
// Expected:
//  string(5) "string"
```

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

### Install Packages for Multi-Mode Worker

Source: https://github.com/roadrunner-server/docs/blob/master/php/worker.md

Install Composer packages required for a single entry point that handles both HTTP and Jobs requests.

```bash
composer require spiral/roadrunner-http spiral/roadrunner-jobs nyholm/psr7
```

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

### Simplified Driver Implementation

Source: https://github.com/roadrunner-server/docs/blob/master/customization/jobs-driver.md

A basic implementation of the `jobs.Driver` interface, including initialization methods (`FromConfig`, `FromPipeline`) and core driver methods (`Push`, `Run`, `State`, `Pause`, `Resume`, `Stop`). This serves as a template for custom drivers.

```go
package driver

import (
	"context"

	"github.com/roadrunner-server/api/v4/plugins/v4/jobs"
	"go.uber.org/zap"
)

var _ jobs.Driver = (*Driver)(nil)

type Configurer interface {
	// UnmarshalKey takes a single key and unmarshal it into a Struct.
	UnmarshalKey(name string, out any) error
	// Has checks if a config section exists.
	Has(name string) bool
}

type Driver struct {
}

func FromConfig(configKey string, log *zap.Logger, cfg Configurer, pipeline jobs.Pipeline, pq jobs.Queue) (*Driver, error) {
	return &Driver{}, nil
}

// FromPipeline initializes consumer from pipeline
func FromPipeline(pipeline jobs.Pipeline, log *zap.Logger, cfg Configurer, pq jobs.Queue) (*Driver, error) {
	return &Driver{}, nil
}

func (d *Driver) Push(ctx context.Context, job jobs.Message) error {
	return nil
}

func (d *Driver) Run(ctx context.Context, p jobs.Pipeline) error {
	return nil
}

func (d *Driver) State(ctx context.Context) (*jobs.State, error) {
	return nil, nil
}

func (d *Driver) Pause(ctx context.Context, p string) error {
	return nil
}

func (d *Driver) Resume(ctx context.Context, p string) error {
	return nil
}

func (d *Driver) Stop(ctx context.Context) error {
	return nil
}

```

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

### Create Basic RR Instance

Source: https://github.com/roadrunner-server/docs/blob/master/customization/embedding.md

Initialize a new RoadRunner instance with a configuration file and default plugins.

```go
import (
	"github.com/roadrunner-server/roadrunner/v2025/lib"
)

func main() {
	overrides := []string{} // List of configuration overrides
	plugins := lib.DefaultPluginsList() // List of RR plugins to enable
	rr, err := lib.NewRR(".rr.yaml", overrides, plugins)
}
```

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

### Start RoadRunner Server in Background

Source: https://github.com/roadrunner-server/docs/blob/master/app-server/cli.md

Starts the server in background mode using the -p option. This mode creates a .pid file.

```terminal
./rr serve -p
```

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

### Serve with Multiple Included Configurations via CLI

Source: https://github.com/roadrunner-server/docs/blob/master/intro/config.md

This command starts the RoadRunner server using a main configuration file and specifies two additional configuration files to be included. The order of includes matters for overriding values.

```bash
./rr serve -e -c .rr.yaml -o include=".rr.yaml .rr2.yaml"
```

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

### Enable Metrics Plugin

Source: https://github.com/roadrunner-server/docs/blob/master/lab/metrics.md

Enable the metrics plugin by adding a 'metrics' section to your configuration file. This example sets the address for the metrics server.

```yaml
version: "3"

metrics:
  address: 127.0.0.1:2112
```

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

### Configure HTTP/3 Server with Static Certificates

Source: https://github.com/roadrunner-server/docs/blob/master/experimental/experimental.md

Set up the HTTP/3 server in .rr.yaml by providing paths to the SSL key and certificate files.

```yaml
version: "3"

server:
  command: "php worker.php"
  relay: pipes

http:
  address: 127.0.0.1:15389
  pool:
    num_workers: 2
  http3:
    address: 127.0.0.1:34555
    key: "localhost+2-key.pem"
    cert: "localhost+2.pem"
```

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

### Dockerfile for RoadRunner with Xdebug

Source: https://github.com/roadrunner-server/docs/blob/master/php/debugging.md

Sets up the Docker image with PHP, Xdebug, Composer, and RoadRunner. It installs Xdebug, configures PHP, and copies the RoadRunner binary.

```dockerfile
FROM ghcr.io/roadrunner-server/roadrunner:2025.1.1 AS roadrunner

FROM php:8.4-cli-alpine3.21

# change version to latest if you want to use the latest version of xDebug, see https://xdebug.org
ENV XDEBUG_VERSION=3.4.4

RUN apk add --no-cache autoconf g++ make postgresql-dev coreutils --update linux-headers \
    && pecl install xdebug-$XDEBUG_VERSION \
    && rm -rf /tmp/pear \
    && docker-php-ext-configure pgsql --with-pgsql=/usr/local/pgsql \
    && docker-php-ext-install pdo_pgsql sockets \
    && docker-php-ext-enable xdebug \
    && apk del linux-headers make g++ autoconf

RUN mv $PHP_INI_DIR/php.ini-development $PHP_INI_DIR/php.ini
COPY xdebug.ini /usr/local/etc/php/conf.d/xdebug.ini

RUN curl -sS https://getcomposer.org/installer | php \
    && mv composer.phar /usr/local/bin/composer \
    && chmod +x /usr/local/bin/composer

RUN addgroup -g 1000 app && adduser -u 1000 -G app -s /bin/sh -D app

WORKDIR /app

COPY --from=roadrunner /usr/bin/rr /usr/local/bin/rr

RUN chown app:app /usr/local/bin/rr && chmod +x /usr/local/bin/rr

USER app
```

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

### Install RoadRunner HTTP and PSR-7 Packages

Source: https://github.com/roadrunner-server/docs/blob/master/php/worker.md

Install the necessary Composer packages for creating an HTTP worker using the PSR-7 server API.

```bash
composer require spiral/roadrunner-http nyholm/psr7
```

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

### KV Plugin Configuration Example

Source: https://github.com/roadrunner-server/docs/blob/master/kv/overview-kv.md

A basic .rr.yaml configuration for the KV plugin, defining a 'memory' driver. Ensure RPC is configured to interact with the plugin.

```yaml
version: "3"

rpc:
  listen: tcp://127.0.0.1:6001

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

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

### Install RoadRunner KV PHP Package

Source: https://github.com/roadrunner-server/docs/blob/master/kv/overview-kv.md

Install the RoadRunner KV PHP package using Composer. This package simplifies integration with your PHP application.

```bash
composer require spiral/roadrunner-kv
```

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

### Install RoadRunner Metrics PHP Package

Source: https://github.com/roadrunner-server/docs/blob/master/lab/metrics.md

Install the RoadRunner metrics PHP package using Composer. This package simplifies integration with the metrics plugin.

```bash
composer require spiral/roadrunner-metrics
```

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

### Create a New Service

Source: https://github.com/roadrunner-server/docs/blob/master/plugins/service.md

Create a new service with specified parameters like name, command, process count, and environment variables. Handles potential ServiceException during creation.

```php
use Spiral\RoadRunner\Services\Exception\ServiceException;

try {
    $result = $manager->create(
        name: 'listen-jobs',
        command: 'php app.php queue:listen',
        processNum: 3,
        execTimeout: 0,
        remainAfterExit: false,
        env: ['APP_ENV' => 'production'],
        restartSec: 30
    );
    
    if (!$result) {
        throw new ServiceException('Service creation failed.');
    }
} catch (ServiceException $e) {
    // handle exception
}
```

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

### Specify Configuration File and Working Directory

Source: https://github.com/roadrunner-server/docs/blob/master/intro/config.md

Combine the -c and -w flags to specify both the configuration file path and the working directory.

```bash
./rr serve -c .rr-dev.yaml -w /path/to/project
```

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

### Start RoadRunner Server in Debug Mode

Source: https://github.com/roadrunner-server/docs/blob/master/app-server/cli.md

Starts the server in debug mode using the -d option, enabling the Golang pprof server on port 6061.

```terminal
./rr serve -d -c .rr.yaml
```

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

### Install RoadRunner App Logger Package

Source: https://github.com/roadrunner-server/docs/blob/master/lab/applogger.md

Install the RoadRunner app-logger PHP package using Composer. This package simplifies the integration of the app-logger plugin with your PHP application.

```bash
composer require roadrunner-php/app-logger
```

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

### Build and Package Go Application for AWS Lambda

Source: https://github.com/roadrunner-server/docs/blob/master/app-server/aws-lambda.md

Compile your Go application into a static binary suitable for AWS Lambda and then create a zip archive for deployment. Ensure you use the correct environment variables for your PHP binary and dependencies.

```bash
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -trimpath -ldflags "-s" -o bootstrap-amd64 main.go plugin.go
zip main.zip * -r
```