Laravel Octane lets you use Roadrunner.

But, instead of using the provided rr binary why not compile your own? Compiling Roadrunner lets you extend your app by writing Go plugins and middleware.

The conventions on how to compile Roadrunner have changed in version 2. It’s now done with a tool called Velox.

Tutorial

In an existing Laravel application, install Octane:

 
composer require laravel/octane
php artisan octane:install

Pick Roadrunner as the application server and install the dependency. This will download rr into the Laravel folder.

Tip: If Roadrunner fails to download make sure you don’t already have another version in your path. If you do, delete that stray version and try again.

At this point the default Roadrunner configuration should work. Try it out to make sure.

 
php artisan octane:start

Next, we’re ready to replace the downloaded rr binary with our own compiled version. To build it we need Go 1.18+ There are many ways to install Go. Here’s one way for MacOS:

 
brew install go

I also have this in my .bash_profile file:

 
export GOPATH="${HOME}/go"
export GOROOT="$(brew --prefix golang)/libexec"
export PATH="$PATH:${GOPATH}/bin:${GOROOT}/bin"
export GO111MODULE="on"

After installing Go, install Velox:

 
go install github.com/roadrunner-server/velox/vx@latest

Next, create a new plugins.toml file in your Laravel folder. This file lists all the Roadrunner plugins to compile. There are many plugins! This example compiles all of them.

 
[velox]
build_args = ['-trimpath', '-ldflags', '-s -X github.com/roadrunner-server/roadrunner/v2/internal/meta.version=v2.10.2 -X github.com/roadrunner-server/roadrunner/v2/internal/meta.buildTime=10:00:00']

[roadrunner]
ref = "v2.10.2"

[github]
    [github.token]
    token = "__REPLACE_ME__"

    [github.plugins]
    # ref → master, commit or tag
    logger = { ref = "master", owner = "roadrunner-server", repository = "logger" }
    temporal = { ref = "master", owner = "temporalio", repository = "roadrunner-temporal" }
    metrics = { ref = "master", owner = "roadrunner-server", repository = "metrics" }
    cache = { ref = "master", owner = "roadrunner-server", repository = "cache" }
    reload = { ref = "master", owner = "roadrunner-server", repository = "reload" }
    otel = { ref = "master", owner = "roadrunner-server", repository = "otel" }
    server = { ref = "master", owner = "roadrunner-server", repository = "server" }
    service = { ref = "master", owner = "roadrunner-server", repository = "service" }
    amqp = { ref = "master", owner = "roadrunner-server", repository = "amqp" }
    beanstalk = { ref = "master", owner = "roadrunner-server", repository = "beanstalk" }
    boltdb = { ref = "master", owner = "roadrunner-server", repository = "boltdb" }
    broadcast = { ref = "master", owner = "roadrunner-server", repository = "broadcast" }
    fileserver = { ref = "master", owner = "roadrunner-server", repository = "fileserver" }
    grpc = { ref = "master", owner = "roadrunner-server", repository = "grpc" }
    gzip = { ref = "master", owner = "roadrunner-server", repository = "gzip" }
    headers = { ref = "master", owner = "roadrunner-server", repository = "headers" }
    http = { ref = "master", owner = "roadrunner-server", repository = "http" }
    jobs = { ref = "master", owner = "roadrunner-server", repository = "jobs" }
    memory = { ref = "master", owner = "roadrunner-server", repository = "memory" }
    nats = { ref = "master", owner = "roadrunner-server", repository = "nats" }
    new_relic = { ref = "master", owner = "roadrunner-server", repository = "new_relic" }
    prometheus = { ref = "master", owner = "roadrunner-server", repository = "prometheus" }
    redis = { ref = "master", owner = "roadrunner-server", repository = "redis" }
    sqs = { ref = "master", owner = "roadrunner-server", repository = "sqs" }
    static = { ref = "master", owner = "roadrunner-server", repository = "static" }
    status = { ref = "master", owner = "roadrunner-server", repository = "status" }
    kv = { ref = "master", owner = "roadrunner-server", repository = "kv" }
    memcached = { ref = "master", owner = "roadrunner-server", repository = "memcached" }
    tcp = { ref = "master", owner = "roadrunner-server", repository = "tcp" }
    rpc = { ref = "master", owner = "roadrunner-server", repository = "rpc" }
    uuid = { ref = "master", owner = "connerbw", repository = "uuid" }


[log]
level = "debug"
mode = "development"

Tip: Make sure to replace the github.token or you will get access denied errors. If your repos are public you don’t need any special permissions.

Near the end of the plugins section pay special attention to this line.

 
uuid = { ref = "master", owner = "connerbw", repository = "uuid" }

This line represents a custom RPC plugin written in Go. The code comments of the plugin act as a sort of guide if ever you want to write your own. Study it.

https://github.com/connerbw/uuid/blob/master/plugin.go

Next, cd to your Laravel folder and compile your plugins.toml with Velox.

 
vx build -c plugins.toml -o ~/path/to/your/laravel/app

Tip: Replace ~/path/to/your/laravel/app with your own. Delete the rr binary before compiling to avoid a write permission error.

After it compiles, add this code to routes/web.php to test it out.

 
Route::get('/uuid', function () {
  $rpc = Spiral\Goridge\RPC\RPC::create(Spiral\RoadRunner\Environment::fromGlobals()->getRPCAddress());
  return $rpc->call('uuid.Generate', 'not-used');
});

Restart Laravel Octane and navigate to the new route.

If it all works then PHP is communicating to the new Go plugin over RPC bus. Good times!

This blog post is about Spiral Framework and Roadrunner Server. I’ll briefly talk about what they are, then show how to compile a custom Roadrunner server, start developing with Spiral, using Docker.

Explain Like I’m 5 PHP Developers

Roadrunner works by creating a HTTP server with Golang’s excellent net/http package, and using Goridge as a bridge to pass PSR7 Request and Responses between PHP and Go. The PHP application is then a long-running, already bootstrapped PSR7-capable application that received the already parsed PSR7 request, dispatches it, and collects the response to give back into Go. [1]

Roadrunner offloads unnecessary operations from PHP to a more optimized server, and effectively swaps out the classic setup of Nginx+FPM with a PHP/Golang application that boosts flexibility and performance. [2]

Roadrunner can serve static files without the presence of Nginx, therefore, simplifying the creation of Docker containers. [3]

You can extend your PHP application by including Go libraries, [4], writing Go HTTP middleware, [5], or tweaking and extending the Roadrunner server. [6]

Spiral is a PHP Framework with a customized Roadrunner server. The main difference is that, when you use Spiral’s version of Roadrunner, it comes with more out-of-the-box solutions for PHP developers, Ie.

• Spiral: spiral/framework/blob/master/main.go
• Roadrunner: spiral/roadrunner/blob/master/cmd/rr/main.go

It’s possible to download the server pre-compiled, but that takes away our power of writing Go code. In this tutorial we start from scratch.

Let’s Go!

The instructions are for Mac, and assume you already have Docker Desktop installed, but the same concepts should work for Linux, and probably Windows.

Step 1

Create a directory for your project.
(If you want, replace hello-spiral with some other name.)

mkdir ~/hello-spiral

Step 2

Create a subdirectory called ./server/ and copy these files into it:

• https://github.com/spiral/framework/blob/master/main.go
• https://github.com/spiral/framework/blob/master/go.mod

Example:

 
cd ~/hello-spiral
mkdir server
cd server
wget https://raw.githubusercontent.com/spiral/framework/master/main.go
wget https://raw.githubusercontent.com/spiral/framework/master/go.mod

Step 3

Download this Dockerfile into the root dir of ~/hello-spiral

The first stage compiles the app server, the second stage installs the Spiral skeleton app.

Step 4

Your file tree should look like this:

Build a new Docker image:

cd ~/hello-spiral
docker build -t hello-spiral .

Step 5

Run the new Docker image:

docker run -it -p 8080:8080 -p 2112:2112 hello-spiral

Step 6

Go to http://localhost:8080 and verify that it works.

Tada! It runs, but how do we develop?

Step 7

Let’s copy all the PHP files that were successfully installed in the container to our host, then mount them.

While the container is still running from Step 5, in another shell, do:

cd ~/hello-spiral
docker ps

This command will output your container ID:

Use your ID in the next command (replace 1f057ae4e473 with your own id):

docker cp 1f057ae4e473:/var/www/app/. src

In the shell tab that is still running the server, stop the server (ctrl-c), then restart with a slight variation of the command from Step 5:

docker run -it -p 8080:8080 -p 2112:2112 -v "$(pwd)"/src:/var/www/app:cached hello-spiral

Keep Going!

Your local PHP files are now mounted in ~/hello-spiral/src, start developing! Change your Dockerfile:

# Setup Spiral
# RUN composer create-project spiral/app . --no-scripts
# Or comment above, uncomment below, and copy Spiral 
COPY ./src/ .

If you make changes in ~/hello-spiral/server, rebuild!