RoadRunner ⇆ Laravel bridge
Easy way for connecting RoadRunner and Laravel applications.
🐋 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 "^5.2"
Installed
composeris 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-laravelcomposer 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-laravelcomposer require spiral/roadrunner-laravel "^4.0"
- Update your
.rr.yamlconfig (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"
- Optionally change relay to socket or TCP port:
- Update RR binary file (using
roadrunner-clior download from binary releases page) up tov2.x - Update RoadRunner starting (
rr serve ...) flags --vand-dmust be not used anymore - In your application code replace
Spiral\RoadRunner\PSR7ClientwithSpiral\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
windowspath must be full (eg.:php vendor/spiral/roadrunner-laravel/bin/rr-worker start)
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: ["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
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.
8 Nov 26, 2022
1 May 4, 2022
55 Dec 12, 2022
311 Dec 31, 2022
26 Nov 17, 2022
3.3k Jan 1, 2023
14 Aug 14, 2022
5.3k Jan 1, 2023
229 Dec 25, 2022
621 Jan 8, 2023
7 Nov 1, 2022
217 Nov 15, 2022
2 Mar 24, 2022
3 Nov 17, 2021
1 Nov 15, 2021
9 Oct 21, 2021
3.7k Dec 29, 2022
1 Dec 5, 2021