roadrunner-php/laravel-bridge

Laravel integration for RoadRunner with support for HTTP, Jobs, gRPC, and Temporal plugins - going beyond Octane's capabilities

6.0.0-beta.1 2025-05-04 16:32 UTC

Requires

• php: ^8.2
• laravel/octane: ^2.9
• spiral/roadrunner-cli: ^2.7
• spiral/roadrunner-grpc: ^3.5
• spiral/roadrunner-http: ^3.0
• spiral/roadrunner-jobs: ^4.0
• spiral/roadrunner-kv: ^4.0
• spiral/roadrunner-worker: ^3.0
• temporal/sdk: ^2.0

Requires (Dev)

• guzzlehttp/guzzle: ^7.0
• laravel/framework: ^12.0
• mockery/mockery: ^1.6
• phpstan/phpstan: ^2.1
• phpunit/phpunit: ^10.0
• rector/rector: ^2.0
• spiral/code-style: ^2.2.2

MIT

• butschster
• roxblnfk
• tarampampam

• queue
• http
• cache
• Bridge
• laravel
• temporal
• gRPC
• roadrunner

README

RoadRunner ⇆ Laravel bridge

Easy way for connecting RoadRunner and Laravel applications (community integration).

Why Use This Package?

Laravel provides the Octane package which partially supports RoadRunner as an application server, but RoadRunner offers much more than just HTTP capabilities. It also includes Jobs, Temporal, gRPC, and other plugins.

Note: There is an article that explains all the RoadRunner plugins: https://butschster.medium.com/roadrunner-an-underrated-powerhouse-for-php-applications-46410b0abc

The main limitation of Octane is that it has a built-in worker only for the HTTP plugin and doesn't provide the ability to create additional workers for other RoadRunner plugins, restricting its use to just the HTTP plugin.

Our Laravel Bridge solves this problem by taking a different approach:

1. We include laravel/octane in our package and reuse its SDK for clearing the state of Laravel applications
2. We add support for running and configuring multiple workers for different RoadRunner plugins
3. By reusing Octane's functionality for state clearing, we automatically support all third-party packages that are compatible with Octane

This way, you get the best of both worlds: Octane's state management and RoadRunner's full plugin ecosystem.

Installation

composer require roadrunner-php/laravel-bridge

After that you can "publish" package configuration file (./config/roadrunner.php) using next command:

php artisan vendor:publish --provider='Spiral\RoadRunnerLaravel\ServiceProvider' --tag=config

Usage

After package installation, you can download and install RoadRunner binary using roadrunner-cli:

./vendor/bin/rr get

Basic Configuration (.rr.yaml)

Create a .rr.yaml configuration file in your project root:

version: '3'
rpc:
  listen: 'tcp://127.0.0.1:6001'

server:
  command: 'php vendor/bin/rr-worker start'
  relay: pipes

http:
  address: 0.0.0.0:8080
  middleware: [ "static", "headers", "gzip" ]
  pool:
    #max_jobs: 64 # feel free to change this
    supervisor:
      exec_ttl: 60s
  headers:
    response:
      X-Powered-By: "RoadRunner"
  static:
    dir: "public"
    forbid: [ ".php" ]

RoadRunner Worker Configuration

You can configure workers in config/roadrunner.php file in the workers section:

use Spiral\RoadRunner\Environment\Mode;
use Spiral\RoadRunnerLaravel\Grpc\GrpcWorker;
use Spiral\RoadRunnerLaravel\Http\HttpWorker;
use Spiral\RoadRunnerLaravel\Queue\QueueWorker;
use Spiral\RoadRunnerLaravel\Temporal\TemporalWorker;

return [
    // ... other configuration options ...

    'workers' => [
        Mode::MODE_HTTP => HttpWorker::class,
        Mode::MODE_JOBS => QueueWorker::class,
        Mode::MODE_GRPC => GrpcWorker::class,
        Mode::MODE_TEMPORAL => TemporalWorker::class,
    ],
];

As you can see, there are several predefined workers for HTTP, Jobs, gRPC, and Temporal. Feel free to replace any of them with your implementation if needed. Or create your own worker, for example, for Centrifugo, TCP or any other plugin.

How It Works

In the server section of the RoadRunner config, we specify the command to start our worker:

server:
  command: 'php vendor/bin/rr-worker start'
  relay: pipes

When RoadRunner server creates a worker pool for a specific plugin, it exposes an environment variable RR_MODE that indicates which plugin is being used. Our worker checks this variable to determine which Worker class should handle the request based on the configuration in roadrunner.php.

The selected worker starts listening for requests from the RoadRunner server and handles them using the Octane worker, which clears the application state after each task (request, command, etc.).

Supported Plugins

HTTP Plugin

The HTTP plugin enables serving HTTP requests with your Laravel application through RoadRunner.

Configuration

Ensure your .rr.yaml has the HTTP section configured:

http:
  address: 0.0.0.0:8080
  middleware: [ "static", "headers", "gzip" ]
  pool:
    max_jobs: 64
  static:
    dir: "public"
    forbid: [ ".php" ]

Note: Read more about the HTTP plugin in the [RoadRunner documentation][https://docs.roadrunner.dev/docs/http/http].

Jobs (Queue) Plugin

The Queue plugin allows you to use RoadRunner as a queue driver for Laravel.

Configuration

First, add the Queue Service Provider in your config/app.php:

'providers' => [
    // ... other providers
    Spiral\RoadRunnerLaravel\Queue\QueueServiceProvider::class,
],

Then, configure a new connection in your config/queue.php:

'connections' => [
    // ... other connections
   'roadrunner' => [
      'driver' => 'roadrunner',
      'queue' => env('RR_QUEUE', 'default'),
      'retry_after' => (int) env('RR_QUEUE_RETRY_AFTER', 90),
      'after_commit' => false,
   ],
],

Update your .rr.yaml file to include the Jobs section:

jobs:
  pool:
    num_workers: 4
  pipelines:
    default:
      driver: memory
      config: { }

Note: Read more about the Jobs plugin in the [RoadRunner documentation][https://docs.roadrunner.dev/docs/queues-and-jobs/overview-queues].

Don't forget to set the QUEUE_CONNECTION environment variable in your .env file:

QUEUE_CONNECTION=roadrunner

That's it! You can now dispatch jobs to the RoadRunner queue without any additional services like Redis or Database.

gRPC Plugin

The gRPC plugin enables serving gRPC services with your Laravel application.

Configuration

Configure gRPC in your .rr.yaml:

grpc:
  listen: 'tcp://0.0.0.0:9001'
  proto:
    - "proto/service.proto"

Then, add your gRPC services to config/roadrunner.php:

return [
    // ... other configuration
    'grpc' => [
        'services' => [
            \App\GRPC\EchoServiceInterface::class => \App\GRPC\EchoService::class,
        ],
    ],
];

Temporal

Temporal is a workflow engine that enables orchestration of microservices and provides sophisticated workflow mechanisms.

Configuration

First, configure Temporal in your .rr.yaml:

temporal:
  address: 127.0.0.1:7233
  activities:
    num_workers: 10

Then, configure your workflows and activities in config/roadrunner.php:

return [
    // ... other configuration
    'temporal' => [
        'address' => env('TEMPORAL_ADDRESS', '127.0.0.1:7233'),
        'namespace' => 'default',
        'declarations' => [
            \App\Temporal\Workflows\MyWorkflow::class,
            \App\Temporal\Activities\MyActivity::class,
        ],
    ],
];

Starting RoadRunner Server

To start the RoadRunner server:

./rr serve

Custom Workers

You can create your own custom workers by implementing the Spiral\RoadRunnerLaravel\WorkerInterface:

namespace App\Workers;

use Spiral\RoadRunnerLaravel\WorkerInterface;
use Spiral\RoadRunnerLaravel\WorkerOptionsInterface;

class CustomWorker implements WorkerInterface
{
    public function start(WorkerOptionsInterface $options): void
    {
        // Your custom worker implementation
    }
}

Then register it in the config/roadrunner.php:

return [
    'workers' => [
        'custom' => \App\Workers\CustomWorker::class,
    ],
];

Support

If you find any package errors, please, make an issue in a current repository.

License

MIT License (MIT). Please see LICENSE for more information.