RoadRunner ⇆ Laravel bridge

Source code of this package was transferred from avto-dev/roadrunner-laravel package by its author. Release v3.3.0 are same in both packages. Any future releases will be published in this repository (previous package was abandoned).

Easy way for connecting RoadRunner and Laravel applications.

Installation

Require this package with composer using next command:

$ composer require spiral/roadrunner-laravel "^3.4"

Installed composer is required (how to install composer).

You need to fix the major version of package.

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

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

And basic RoadRunner configuration file (./.rr.yaml.dist):

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

After that you can modify configuration files as you wish.

Important: despite the fact that worker allows you to refresh application instance on each HTTP request (if environment variable APP_REFRESH set to true), we strongly recommend to avoid 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.

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 outcoming responses using laravel events system. Also events 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:

env:
  #APP_REFRESH: true

http:
  address: 0.0.0.0:8080
  workers:
    command: 'php ./vendor/bin/rr-worker'

static:
  dir: 'public'

Roadrunner server starting:

$ rr -c ./.rr.yaml serve -d

Listeners

This package provides event listeners for resetings 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.

Environment variables

You can use the following environment variables:

Variable name	Description
`APP_FORCE_HTTPS`	(declared in configuration file) Forces application HTTPS schema usage
`APP_REFRESH`	Refresh application instance on every request

Known issues

Controller constructors

You should avoid to use HTTP controller constructors (created or resolved instances in constructor can be shared between different requests). Use dependencies resolving in 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 will find any package errors, please, make an issue in current repository.

License

MIT License (MIT). Please see LICENSE for more information. Maintained by tarampampam and Spiral Scout.

sikhlana / roadrunner-laravel