Package

Spiral Roadrunner Laravel

RoadRunner: Bridge for Laravel applications

Package

spiral/roadrunner-laravel

View on GitHub →

logo

RoadRunner ⇆ Laravel bridge

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

πŸ‹ If you want to see an example of a laravel application in a docker container with RoadRunner as a web server - take a look at this repository.

Installation

Make sure that RR binary file already installed on your system (or docker image). Require this package with composer using next command:

$ composer require spiral/roadrunner-laravel

Installed composer is required (how to install composer).

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

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

Important: despite the fact that worker allows you to refresh application instance on each HTTP request (if worker started with option --refresh-app, eg.: php ./vendor/bin/rr-worker start --refresh-app), we strongly recommend avoiding this for performance reasons. Large applications can be hard to integrate with RoadRunner (you must decide which of service providers must be reloaded on each request, avoid "static optimization" in some cases), but it's worth it.

Upgrading guide

v4.x β†’ v5.x
  • Update current package in your application:
    • composer remove spiral/roadrunner-laravel
    • composer require spiral/roadrunner-laravel "^5.0"
  • Update package configuration file (roadrunner.php; take a look for actual example in current repository)
v3.x β†’ v4.x
  • Update current package in your application:
    • composer remove spiral/roadrunner-laravel
    • composer require spiral/roadrunner-laravel "^4.0"
  • Update your .rr.yaml config (take a look for sample here) - a lot of options was changed
    • Optionally change relay to socket or TCP port:
      server:
        command: "php ./vendor/bin/rr-worker start --relay-dsn unix:///var/run/rr-relay.sock"
        relay: "unix:///var/run/rr-relay.sock"
      
  • Update RR binary file (using roadrunner-cli or download from binary releases page) up to v2.x
  • Update RoadRunner starting (rr serve ...) flags - -v and -d must be not used anymore
  • In your application code replace Spiral\RoadRunner\PSR7Client with Spiral\RoadRunner\Http\PSR7Worker

Usage

After package installation you can use provided "binary" file as RoadRunner worker: ./vendor/bin/rr-worker. This worker allows you to interact with incoming requests and outgoing responses using laravel events system. Event contains:

Event classname Application object HTTP server request HTTP request HTTP response Exception
BeforeLoopStartedEvent βœ”
BeforeLoopIterationEvent βœ” βœ”
BeforeRequestHandlingEvent βœ” βœ”
AfterRequestHandlingEvent βœ” βœ” βœ”
AfterLoopIterationEvent βœ” βœ” βœ”
AfterLoopStoppedEvent βœ”
LoopErrorOccurredEvent βœ” βœ” βœ”

Simple .rr.yaml config example (full example can be found here):

For windows path must be full (eg.: php vendor/spiral/roadrunner-laravel/bin/rr-worker start)

version: "2.7"

server:
  command: "php ./vendor/bin/rr-worker start --relay-dsn unix:///var/run/rr-relay.sock"
  relay: "unix:///var/run/rr-relay.sock"

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"]

Socket or TCP port relay usage is strongly recommended for avoiding problems with dd(), dump(), echo() and other similar functions, that sends data to the IO pipes.

Roadrunner server starting:

$ rr serve -c ./.rr.yaml

Listeners

This package provides event listeners for resetting application state without full application reload (like cookies, HTTP request, application instance, service-providers and other). Some of them already declared in configuration file, but you can declare own without any limitations.

Helpers

This package provides the following helpers:

Name Description
\rr\dump(...) Dump passed values (dumped result will be available in the HTTP response)
\rr\dd(...) Dump passed values and stop the execution
\rr\worker() Easy access to the RoadRunner PSR worker instance

Known issues

Performance degradation

...when file driver is set for your sessions. Please, use redis (or something similar) driver instead (related issue). This package or/and RoadRunner has nothing to do with it, but since this is a fairly common issue - it is described here.

Controller constructors

You should avoid to use HTTP controller constructors (created or resolved instances in a constructor can be shared between different requests). Use dependencies resolving in a controller methods instead.

Bad:

<?php

use Illuminate\Http\Request;
use Illuminate\Http\Response;
use App\Http\Controllers\Controller;

class UserController extends Controller
{
    /**
     * The user repository instance.
     */
    protected $users;

    /**
     * @var Request
     */
    protected $request;

    /**
     * @param UserRepository $users
     * @param Request        $request
     */
    public function __construct(UserRepository $users, Request $request)
    {
        $this->users   = $users;
        $this->request = $request;
    }

    /**
     * @return Response
     */
    public function store(): Response
    {
        $user = $this->users->getById($this->request->id);

        // ...
    }
}

Good:

<?php

use Illuminate\Http\Request;
use Illuminate\Http\Response;
use App\Http\Controllers\Controller;

class UserController extends Controller
{
    /**
     * @param  Request        $request
     * @param  UserRepository $users
     *
     * @return Response
     */
    public function store(Request $request, UserRepository $users): Response
    {
        $user = $users->getById($request->id);

        // ...
    }
}
Middleware constructors

You should never to use middleware constructor for session, session.store, auth or auth Guard instances resolving and storing in properties (for example). Use method-injection or access them through Request instance.

Bad:

<?php

use Illuminate\Http\Request;
use Illuminate\Session\Store;

class Middleware
{
    /**
     * @var Store
     */
    protected $session;

    /**
     * @param Store $session
     */
    public function __construct(Store $session)
    {
        $this->session = $session;
    }

    /**
     * Handle an incoming request.
     *
     * @param Request  $request
     * @param \Closure $next
     *
     * @return mixed
     */
    public function handle(Request $request, Closure $next)
    {
        $name = $this->session->getName();

        // ...

        return $next($request);
    }
}

Good:

<?php

use Illuminate\Http\Request;

class Middleware
{
    /**
     * Handle an incoming request.
     *
     * @param Request  $request
     * @param \Closure $next
     *
     * @return mixed
     */
    public function handle(Request $request, Closure $next)
    {
        $name = $request->session()->getName();
        // $name = resolve('session')->getName();

        // ...

        return $next($request);
    }
}

Testing

For package testing we use phpunit framework and docker-ce + docker-compose as develop environment. So, just write into your terminal after repository cloning:

$ make build
$ make latest # or 'make lowest'
$ make test

Changes log

Changes log can be found here.

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. Maintained by tarampampam and Spiral Scout.

Spiral Roadrunner Laravel Related Articles

RoadRunner Key-Value Cache for Laravel image

RoadRunner Key-Value Cache for Laravel

Read article
Laravel Octane Adds Support for Roadrunner v3 image

Laravel Octane Adds Support for Roadrunner v3

Read article
A quick guide on why you should use Laravel Octane to scale your app image

A quick guide on why you should use Laravel Octane to scale your app

Read article
Laravel Octane image

Laravel Octane

Read article
90 Laravel Tutorials, Packages, and Resources from 2023 image

90 Laravel Tutorials, Packages, and Resources from 2023

Read article
Laravel Octane v1.0 is Here image

Laravel Octane v1.0 is Here

Read article

Acquaint Softtech

Acquaint Softtech offers AI-ready Laravel developers who onboard in 48 hours at $3000/Month with no lengthy sales process and a 100 percent money-back guarantee.

Acquaint Softtech

Let your users buy domains without leaving your app

If your Laravel app gives users a site, a storefront, or a workspace, they’ll eventually want their own domain. The name.com API lets them search, register, and connect one without leaving your product. It’s a clean REST API, so Laravel’s HTTP client is all you need.

Let your users buy domains without leaving your app

PhpStorm

The go-to PHP IDE with extensive out-of-the-box support for Laravel and its ecosystem.

PhpStorm

Kirschbaum

Providing innovation and stability to ensure your web application succeeds.

Kirschbaum

Shift

Running an old Laravel version? Instant, automated Laravel upgrades and code modernization to keep your applications fresh.

Shift

Harpoon: Next generation time tracking and invoicing

The next generation time-tracking and billing software that helps your agency plan and forecast a profitable future.

Harpoon: Next generation time tracking and invoicing