diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 133 |
1 files changed, 91 insertions, 42 deletions
@@ -7,13 +7,14 @@ RoadRunner [](https://scrutinizer-ci.com/g/spiral/roadrunner/?branch=master) [](https://codecov.io/gh/spiral/roadrunner/) -High-Performance PSR-7 PHP application server, load balancer and process manager. +RoadRunner is an open source (MIT licensed), high-performance PSR-7 PHP application server, load balancer and process manager. +It supports service model with ability to extend it's functionality on a project basis. Features: -------- - PSR-7 HTTP server (file uploads, error handling, static files, hot reload, middlewares, event listeners) - extendable service model (plus PHP compatible RPC server) -- no external services, drop-in (based on [Goridge](https://github.com/spiral/goridge)) +- no external PHP dependencies, drop-in (based on [Goridge](https://github.com/spiral/goridge)) - load balancer, process manager and task pipeline - frontend agnostic (queue, REST, PSR-7, async php, etc) - works over TCP, unix sockets and standard pipes @@ -26,33 +27,32 @@ Features: - very fast (~250k rpc calls per second on Ryzen 1700X over 16 threads) - works on Windows -Installation: +Getting Started: -------- -``` -$ go get github.com/spiral/roadrunner -$ composer require spiral/roadrunner -``` -Usage: ------- +#### Getting RoadRunner +The easiest way to get the latest RoadRunner version is to use one of the pre-built release binaries which are available for +OSX, Linux, FreeBSD, and Windows. Instructions for using these binaries are on the GitHub [releases page](https://github.com/spiral/roadrunner/releases). + +#### Building RoadRunner: +RoadRunner can be compiled on Linux, OSX, Windows and other 64 bit environments as the only requirement is Go 1.8+ itself. + +To build: ``` -$ cd cmd -$ cd rr -$ go build && go install -$ cp .rr.yaml path/to/the/project +$ make ``` -> TODO: To be updated with build scripts! +To test: ``` -$ rr serve -v +$ make test ``` -Example [worker](https://github.com/spiral/roadrunner/blob/master/php-src/tests/http/client.php). +Using RoadRunner: +-------- -Example config: ---------------- +In order to use RoadRunner you only have to place `.rr.yaml` file in a root of your php project: ```yaml # rpc bus allows php application and external clients to talk to rr services. @@ -95,16 +95,16 @@ http: # maximum jobs per worker, 0 - unlimited. maxJobs: 0 - # for how long pool should attempt to allocate free worker (request timeout). In nanoseconds for now :( - allocateTimeout: 600000000 + # for how long pool should attempt to allocate free worker (request timeout). Nanoseconds atm. + allocateTimeout: 1000000000 - # amount of time given to worker to gracefully destruct itself. In nanoseconds for now :( - destroyTimeout: 600000000 + # amount of time given to worker to gracefully destruct itself. Nanoseconds atm. + destroyTimeout: 1000000000 # static file serving. static: # serve http static files - enable: false + enable: true # root directory for static file (http would not serve .php and .htaccess files). dir: "public" @@ -113,23 +113,76 @@ static: forbid: [".php", ".htaccess"] ``` -Examples: +Where `psr-worker.php`: + +```php +$psr7 = new RoadRunner\PSR7Client(new RoadRunner\Worker($relay)); + +while ($req = $psr7->acceptRequest()) { + try { + $resp = new \Zend\Diactoros\Response() + $resp->getBody()->write("hello world"); + + $psr7->respond($resp); + } catch (\Throwable $e) { + $psr7->getWorker()->error((string)$e); + } +} +``` + +> Check how to init relay [here](./php-src/tests/client.php). + +Working with RoadRunner service: -------- +RoadRunner application can be started by calling simple command from the root of your PHP application. + +``` +$ rr serve +``` + +You can also run RR in debug mode to view all incoming requests. + +``` +$ rr serve -d +``` + +You can force RR service to reload it's http workers. + +``` +$ rr http:reset +``` + +> You can attach this command as file watcher in your IDE. + +To view status of all active workers in interactive mode. + +``` +$ rr http:workers -i +``` + +Standalone Usage: +-------- +You can also use RoadRunner as library in order to drive your application without any additional protocol at top of it. + ```go -p, err := rr.NewPool( - func() *exec.Cmd { return exec.Command("php", "worker.php", "pipes") }, - rr.NewPipeFactory(), - rr.Config{ - NumWorkers: uint64(runtime.NumCPU()), - AllocateTimeout: time.Second, - DestroyTimeout: time.Second, - }, -) -defer p.Destroy() - -rsp, err := p.Exec(&rr.Payload{Body: []byte("hello")}) +srv := NewServer( + &ServerConfig{ + Command: "php client.php echo pipes", + Relay: "pipes", + Pool: &Config{ + NumWorkers: int64(runtime.NumCPU()), + AllocateTimeout: time.Second, + DestroyTimeout: time.Second, + }, + }) +defer srv.Stop() + +srv.Start() + +res, err := srv.Exec(&Payload{Body: []byte("hello")}) ``` + ```php <?php /** @@ -149,13 +202,9 @@ while ($body = $rr->receive($context)) { } } ``` -> Check how to init relay [here](./php-src/tests/client.php). More examples can be found in tests. +> Check how to init relay [here](./php-src/tests/client.php). -Testing: --------- -``` -$ make test -``` +You can find more examples in tests and `php-src` directory. License: -------- |