RoadRunner Service Plugin provides a simple API to monitor and control processes. It is often used to manage background processes, daemons, or services that need to run continuously. The Service Plugin allows you to start, stop, and manage any number of processes, including PHP scripts, binaries, and bash/powershell scripts.
The Service Plugin is configured using a .rr.yaml.
Here is an example configuration:
version: "3"
...
service:
meilisearch:
service_name_in_log: true
remain_after_exit: true
restart_sec: 1
command: "./bin/meilisearch"
centrifuge:
service_name_in_log: true
remain_after_exit: true
restart_sec: 1
command: "./bin/centrifugo --config=centrifugo.json"
some_service_1:
command: "php loop.php"
process_num: 10
exec_timeout: 0s
remain_after_exit: true
service_name_in_log: false
env:
- foo: "BAR"
restart_sec: 1
The service section is where you define your services, with each service having its own configuration settings.
The following are the available configuration settings for each service:
| Setting | Description |
|---|---|
| command | The command to execute. There are no restrictions on commands. It could be a binary, a PHP file, a script, etc. |
| process_num | The number of processes for the command to fire. The default value is 1. |
| exec_timeout | The maximum allowed time to run for the process. The default value is 0s, which means unlimited time. The timeout can be set in the form of 1h, 1m, or 1s (h,m,s). |
| remain_after_exit | If set to true, the process will remain after exit. For example, if you need to restart the process every 10 seconds, exec_timeout should be set to 10s, and remain_after_exit should be set to true. Note that if you kill the process from outside and remain_after_exit is true, the process will be restarted. |
| restart_sec | The delay between process stop and restart. The default value is 30 seconds. |
| service_name_in_log | If set to true, the service name will be shown in the log in the form %plugin%.%service_name%. The default value is false. |
| env | Environment variables to pass to the underlying process from the config. |
Services will be started when RoadRunner starts and will be stopped when RoadRunner stops.
The RoadRunner Service Plugin PHP Client Library allows you to manage processes in PHP application using the Service Plugin. You can use the library to create, start, stop, restart, and manage any number of services.
You can install the package via composer:
composer require spiral/roadrunner-services
To use the library, you need to create an instance of Spiral\RoadRunner\Services\Manager:
use Spiral\RoadRunner\Services\Manager;
use Spiral\Goridge\RPC\RPC;
require __DIR__ . '/vendor/autoload.php';
$manager = new Manager(RPC::create('tcp://127.0.0.1:6001'));
To create a new service, use the create method:
use Spiral\RoadRunner\Services\Exception\ServiceException;
try {
$result = $manager->create(
name: 'listen-jobs',
command: 'php app.php queue:listen',
processNum: 3,
execTimeout: 0,
remainAfterExit: false,
env: ['APP_ENV' => 'production'],
restartSec: 30
);
if (!$result) {
throw new ServiceException('Service creation failed.');
}
} catch (ServiceException $e) {
// handle exception
}
To check the status of a service, use the statuses method:
use Spiral\RoadRunner\Services\Exception\ServiceException;
try {
$status = $manager->statuses(name: 'listen-jobs');
// Will return an array with statuses of every run process
} catch (ServiceException $e) {
// handle exception
}
To restart a service, use the restart method:
use Spiral\RoadRunner\Services\Exception\ServiceException;
try {
$result = $manager->restart(name: 'listen-jobs');
if (!$result) {
throw new ServiceException('Service restart failed.');
}
} catch (ServiceException $e) {
// handle exception
}
To terminate a service, use the terminate method:
use Spiral\RoadRunner\Services\Exception\ServiceException;
try {
$result = $manager->terminate(name: 'listen-jobs');
if (!$result) {
throw new ServiceException('Service termination failed.');
}
} catch (ServiceException $e) {
// handle exception
}
To get a list of all services, use the list method:
use Spiral\RoadRunner\Services\Exception\ServiceException;
try {
$services = $manager->list();
// Will return an array with services names
// ['listen-jobs', 'websocket-connection']
} catch (ServiceException $e) {
// handle exception
}
To make it easy to use the Service proto API in PHP, we provide a GitHub repository, that contains all the generated PHP DTO classes proto files, making it easy to work with these files in your PHP application.
The RoadRunner Lock Plugin allows you to manage locks in your application using RPC API . The API communicates with the Lock Plugin using RPC calls with protobuf payloads.
The Create method is used to create a new lock.
func (r *rpc) Create(in *serviceV1.Create, out *serviceV1.Response) error
The Acquire method is used to acquire a lock.
func (r *rpc) Acquire(in *serviceV1.Acquire, out *serviceV1.Response) error
The Release method is used to release a lock.
func (r *rpc) Release(in *serviceV1.Release, out *serviceV1.Response) error
The Delete method is used to delete a lock.
func (r *rpc) Delete(in *serviceV1.Delete, out *serviceV1.Response) error
The List method is used to list all locks.
func (r *rpc) List(in *serviceV1.List, out *serviceV1.ListResponse) error