Boost PHP Performance with RoadRunner: A Hands‑On Guide

Overview

RoadRunner is a high‑performance PHP application server and process manager written in Go. It uses Go’s goroutine model to keep a pool of long‑living PHP workers, allowing massive concurrency while avoiding the overhead of spawning a new PHP process for each request.

Key Features

High performance : Goroutine‑based concurrency handles many simultaneous requests.

HTTP/2 support : Built‑in HTTP/2 provides multiplexing, flow control and TLS.

Extensibility : Plugins can add custom functionality.

Cross‑platform : Runs on Linux, macOS, Windows and FreeBSD.

Queue support : Enables efficient background and asynchronous tasks.

Simple installation : Distributed as a single binary with Composer integration.

Architecture

RoadRunner creates a pool of PHP workers and routes incoming HTTP requests to them via the goridge protocol. Workers stay alive across requests, so PHP code is loaded only once per worker, dramatically reducing request latency.

Comparison with Nginx + PHP‑FPM

Traditional CGI/FastCGI : The web server launches a new CGI process for each request, passing data via stdin and environment variables. The process exits after the response.

Nginx + PHP‑FPM : Nginx forwards requests to a PHP‑FPM pool. Workers are reused, but PHP code is re‑initialized for every request because each worker starts a fresh PHP interpreter.

RoadRunner : Workers are long‑running PHP processes managed directly by RoadRunner. A request is dispatched to an existing worker, eliminating per‑request PHP bootstrapping and saving CPU and memory.

Installation

Download the pre‑built binary for your OS from the GitHub releases page and extract it into your project directory.

If you manage dependencies with Composer, install the CLI wrapper: composer require spiral/roadrunner-cli Then fetch the latest binary: ./vendor/bin/rr get-binary The rr executable will appear in the project root.

Creating a PSR‑7 Worker

Install the required packages:

composer require spiral/roadrunner-http nyholm/psr7

Create a file named psr-worker.php with the following content:

<?php
declare(strict_types=1);

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

use Nyholm\Psr7\Response;
use Nyholm\Psr7\Factory\Psr17Factory;
use Spiral\RoadRunner\Worker;
use Spiral\RoadRunner\Http\PSR7Worker;

$worker = Worker::create();
$factory = new Psr17Factory();
$psr7 = new PSR7Worker($worker, $factory, $factory, $factory);

while (true) {
    try {
        $request = $psr7->waitRequest();
        if ($request === null) {
            break;
        }
    } catch (\Throwable $e) {
        $psr7->respond(new Response(400));
        continue;
    }

    try {
        $psr7->respond(new Response(200, [], 'Hello RoadRunner!'));
    } catch (\Throwable $e) {
        $psr7->respond(new Response(500, [], 'Something Went Wrong!'));
    }
}

This worker communicates with RoadRunner through standard pipes.

Configuration File

Create .rr.yaml in the project root with the following content:

server:
  command: "php psr-worker.php"

http:
  address: 0.0.0.0:8282

logs:
  level: debug
  mode: development

Running the Server

Make sure the following files are in the current directory:

.rr.yaml

psr-worker.php

rr

(the RoadRunner binary)

Start the server: ./rr serve In development mode you will see log entries similar to:

2024-11-23T12:51:26+0000    DEBUG   server  worker is allocated {"pid":451,"max_execs":0,...}
[INFO] RoadRunner server started; version: 2024.2.1

Accessing the Service

Open a browser at http://127.0.0.1:8282/. The worker will respond with Hello RoadRunner!.