diff options
Diffstat (limited to 'docs/php')
| -rw-r--r-- | docs/php/caveats.md | 13 | ||||
| -rw-r--r-- | docs/php/debugging.md | 29 | ||||
| -rw-r--r-- | docs/php/developer.md | 26 | ||||
| -rw-r--r-- | docs/php/environment.md | 21 | ||||
| -rw-r--r-- | docs/php/error-handling.md | 23 | ||||
| -rw-r--r-- | docs/php/limit.md | 24 | ||||
| -rw-r--r-- | docs/php/restarting.md | 50 | ||||
| -rw-r--r-- | docs/php/rpc.md | 20 | ||||
| -rw-r--r-- | docs/php/worker.md | 122 |
9 files changed, 0 insertions, 328 deletions
diff --git a/docs/php/caveats.md b/docs/php/caveats.md deleted file mode 100644 index 6bb834c4..00000000 --- a/docs/php/caveats.md +++ /dev/null @@ -1,13 +0,0 @@ -# Caveats - -## Uploading Files -Since file-upload is handled on RR end PHP process will only receive the filename of temporary resources. -This resource would not be registered in `uploaded files` hash and, as a result, function `is_uploaded_file` will always return `false`. - -> Reference: https://github.com/spiral/roadrunner/issues/133 - -## Exit and Die functions -Please note that you should not use any of the following methods `die`, `exit`. Use buffered output if your library requires writing content to stdout. - -## WinCache -Using roadrunner on Windows with WinCache extension might cause worker bytecode to stuck in memory. diff --git a/docs/php/debugging.md b/docs/php/debugging.md deleted file mode 100644 index 782ccee6..00000000 --- a/docs/php/debugging.md +++ /dev/null @@ -1,29 +0,0 @@ -# Debugging -You can use RoadRunner scripts with xDebug extension. In order to enable configure your IDE to accept remote connections. - -Note, if you run multiple PHP processes you have to extend the maximum number of allowed connections to the number of -active workers, otherwise some calls would not be caught on your breakpoints. - - - -To activate xDebug make sure to set the `xdebug.mode=debug` in your `php.ini`. - -To enable xDebug in your application make sure to set ENV variable `XDEBUG_SESSION`: - -``` -rpc: - listen: tcp://127.0.0.1:6001 - -server: - command: "php worker.php" - env: - XDEBUG_SESSION: 1 - -http: - address: "0.0.0.0:8080" - pool: - num_workers: 1 - debug: true -``` - -You should be able to use breakpoints and view state at this point. diff --git a/docs/php/developer.md b/docs/php/developer.md deleted file mode 100644 index 6bb7a340..00000000 --- a/docs/php/developer.md +++ /dev/null @@ -1,26 +0,0 @@ -# Developer Mode -RoadRunner uses PHP scripts in daemon mode, this means that you have to reload a server every time you change your codebase. - -If you use any modern IDE you can achieve that by adding file watcher which automatically invokes command `rr reset` for the plugins specified in the `reload` config. - -> Or use [auto-resetter](/beep-beep/reload.md). - -## In Docker -You can reset rr process in docker by connecting to it using local rr client. - -```yaml -rpc: - listen: tcp://:6001 -``` - -> Make sure to forward/expose port 6001. - -Then run `rr reset` locally on file change. - -## Debug Mode -To run workers in debug mode (similar to how PHP-FPM operates): - -```yaml -http: - pool.debug: true -``` diff --git a/docs/php/environment.md b/docs/php/environment.md deleted file mode 100644 index 6ad788af..00000000 --- a/docs/php/environment.md +++ /dev/null @@ -1,21 +0,0 @@ -# Environment configuration -All RoadRunner workers will inherit the system configuration available for the parent server process. In addition, you can -customize the set of env variables to be passed to your workers using part `env` of `.rr` configuration file. - -```yaml -server: - command: "php worker.php" - env: - key: value -``` - -> All keys will be automatically uppercased! - -### Default ENV values -RoadRunner provides set of ENV values to help the PHP process to identify how to properly communicate with the server. - -Key | Description ---- | --- -RR_MODE | Identifies what mode worker should work with ("http", "temporal") -RR_RPC | Contains RPC connection address when enabled. -RR_RELAY | "pipes" or "tcp://...", depends on server relay configuration. diff --git a/docs/php/error-handling.md b/docs/php/error-handling.md deleted file mode 100644 index b8487f36..00000000 --- a/docs/php/error-handling.md +++ /dev/null @@ -1,23 +0,0 @@ -# Error Handling -There are multiple ways of how you can handle errors produces by PHP workers. - -The simplest and most common way would be responding to parent service with the error message using `getWorker()->error()`: - -```php -try { - $resp = new \Zend\Diactoros\Response(); - $resp->getBody()->write("hello world"); - - $psr7->respond($resp); -} catch (\Throwable $e) { - $psr7->getWorker()->error((string)$e); -} -``` - -You can also flush your warning and errors into `STDERR` to output them directly into the console (similar to docker-compose). - -```php -file_put_contents('php://stderr', 'my message'); -``` - -Since RoadRunner 2.0 all warnings send to STDOUT will be forwarded to STDERR as well.
\ No newline at end of file diff --git a/docs/php/limit.md b/docs/php/limit.md deleted file mode 100644 index 154326a5..00000000 --- a/docs/php/limit.md +++ /dev/null @@ -1,24 +0,0 @@ -# Embedded Monitoring -RoadRunner is capable of monitoring your application and run soft reset (between requests) if necessary. The previous name - `limit`, current - `supervisor` - -## Configuration -Edit your `.rr` file to specify limits for your application: - -```yaml -# monitors rr server(s) -http: - address: "0.0.0.0:8080" - pool: - num_workers: 6 - supervisor: - # watch_tick defines how often to check the state of the workers (seconds) - watch_tick: 1s - # ttl defines maximum time worker is allowed to live (seconds) - ttl: 0 - # idle_ttl defines maximum duration worker can spend in idle mode after first use. Disabled when 0 (seconds) - idle_ttl: 10s - # exec_ttl defines maximum lifetime per job (seconds) - exec_ttl: 10s - # max_worker_memory limits memory usage per worker (MB) - max_worker_memory: 100 -```
\ No newline at end of file diff --git a/docs/php/restarting.md b/docs/php/restarting.md deleted file mode 100644 index 1ee05641..00000000 --- a/docs/php/restarting.md +++ /dev/null @@ -1,50 +0,0 @@ -# Restarting Workers -RoadRunner provides multiple ways to safely restart worker(s) on demand. Both approaches can be used on a live server and should not cause downtime. - -## Stop Command -You are able to send `stop` command from worker to parent server to force process destruction. In this scenario, -the job/request will be automatically forwarded to the next worker. - -We can demonstrate it by implementing `max_jobs` control on PHP end: - -```php -<?php - -use Spiral\RoadRunner; -use Nyholm\Psr7; - -include "vendor/autoload.php"; - -$worker = RoadRunner\Worker::create(); -$psrFactory = new Psr7\Factory\Psr17Factory(); - -$worker = new RoadRunner\Http\PSR7Worker($worker, $psrFactory, $psrFactory, $psrFactory); - -$count = 0; -while ($req = $worker->waitRequest()) { - try { - $rsp = new Psr7\Response(); - $rsp->getBody()->write('Hello world!'); - - $count++; - if ($count > 10) { - $worker->getWorker()->stop(); - return; - } - - $worker->respond($rsp); - } catch (\Throwable $e) { - $worker->getWorker()->error((string)$e); - } -} -``` - -> This approach can be used to control memory usage inside the PHP script. - -## Full Reset -You can also initiate a rebuild of all RoadRunner workers using embedded [RPC bus](/beep-beep/rpc.md): - -```php -$rpc = \Spiral\Goridge\RPC\RPC::create('tcp://127.0.0.1:6001'); -$rpc->call('resetter.Reset', 'http'); -``` diff --git a/docs/php/rpc.md b/docs/php/rpc.md deleted file mode 100644 index c7560846..00000000 --- a/docs/php/rpc.md +++ /dev/null @@ -1,20 +0,0 @@ -# RPC to App Server -You can connect to application server via `SocketRelay`: - -```php -$rpc = \Spiral\Goridge\RPC\RPC::create('tcp://127.0.0.1:6001'); -``` - -You can immediately use this RPC to call embedded RPC services such as HTTP: - -```php -var_dump($rpc->call('informer.Workers', 'http')); -``` - -> Please note that in the case of running workers in debug mode (`http: { debug: true }` in `.rr.yaml`) the number -> of http workers will be zero (i.e. an empty array `[]` will be returned). -> -> This behavior may be changed in the future, you should not rely on this result to check that the -> RoadRunner was launched in development mode. - -You can read how to create your own services and RPC methods in [this section](/beep-beep/plugin.md). diff --git a/docs/php/worker.md b/docs/php/worker.md deleted file mode 100644 index 8e6425b8..00000000 --- a/docs/php/worker.md +++ /dev/null @@ -1,122 +0,0 @@ -# PHP Workers - -In order to run your PHP application, you must create a worker endpoint and configure RoadRunner to use it. First, -install the required package using [Composer](https://getcomposer.org/). - -```bash -composer require spiral/roadrunner nyholm/psr7 -``` - -Simplest entrypoint with PSR-7 server API might looks like: - -```php -<?php - -use Spiral\RoadRunner; -use Nyholm\Psr7; - -include "vendor/autoload.php"; - -$worker = RoadRunner\Worker::create(); -$psrFactory = new Psr7\Factory\Psr17Factory(); - -$worker = new RoadRunner\Http\PSR7Worker($worker, $psrFactory, $psrFactory, $psrFactory); - -while ($req = $worker->waitRequest()) { - try { - $rsp = new Psr7\Response(); - $rsp->getBody()->write('Hello world!'); - - $worker->respond($rsp); - } catch (\Throwable $e) { - $worker->getWorker()->error((string)$e); - } -} -``` - -Such a worker will expect communication with the parent RoadRunner server over standard pipes, create `.rr.yaml` config -to enable it: - -```yaml -server: - command: "php psr-worker.php" - -http: - address: 0.0.0.0:8080 - pool: - num_workers: 4 -``` - -If you don't like `yaml` try `.rr.json`: - -```json -{ - "server": { - "command": "path-to-php/php psr-worker.php" - }, - "http": { - "address": "0.0.0.0:8080", - "pool": { - "num_workers": 4 - } - } -} -``` - -You can start the application now by downloading the RR binary file and running `rr serve` - -## Alternative Communication Methods - -PHP Workers would utilize standard pipes STDOUT and STDERR to exchange data frames with RR server. In some cases you might -want to use alternative communication methods such as TCP socket: - -```yaml -server: - command: "php psr-worker.php" - relay: "tcp://localhost:7000" - -http: - address: 0.0.0.0:8080 - pool: - num_workers: 4 -``` - -Unix sockets: - -```yaml -server: - command: "php psr-worker.php" - relay: "unix://rr.sock" - -http: - address: 0.0.0.0:8080 - pool: - num_workers: 4 -``` - -## Troubleshooting - -In some cases, RR would not be able to handle errors produced by PHP worker (PHP is missing, the script is dead etc) -. - -``` -$ rr serve -DEBU[0003] [rpc]: started -DEBU[0003] [http]: started -ERRO[0003] [http]: unable to connect to worker: unexpected response, header is missing: exit status 1 -DEBU[0003] [rpc]: stopped -``` - -You can troubleshoot it by invoking `command` set in `.rr` file manually: - -``` -$ php psr-worker.php -``` - -The worker should not cause any error until any input provided and must fail with invalid input signature after the -first input character. - -## Other Type of Workers - -Different roadrunner implementations might define their own worker APIs, -examples: [GRPC](https://github.com/spiral/php-grpc), [Workflow/Activity Worker](https://docs.temporal.io/docs/php-workers/).
\ No newline at end of file |