service.md

Service

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.

Manage services using RoadRunner config

The Service Plugin is configured using a .rr.yaml.

Here is an example configuration:

{% code title=".rr.yaml" %}

version: "3"

service:
  meilisearch:
    service_name_in_log: true
    timeout_stop_sec: 10
    remain_after_exit: true
    restart_sec: 1
    command: "./bin/meilisearch"
    user: "www-data"
  centrifuge:
    service_name_in_log: true
    timeout_stop_sec: 10
    remain_after_exit: true
    restart_sec: 1
    command: "./bin/centrifugo --config=centrifugo.json"
  some_service_1:
    command: "php loop.php"
    process_num: 10
    timeout_stop_sec: 10
    exec_timeout: 0s
    remain_after_exit: true
    service_name_in_log: false
    env:
      - foo: "BAR"
    restart_sec: 1

{% endcode %}

The service section is where you define your services, with each service having its own configuration settings.

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).
timeout_stop_sec	The maximum allowed time to wait for the process to stop.
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.
user	Username (not UID) for the Service process. An empty value means to use the RR process user.
Services will be started when RoadRunner starts and will be stopped when RoadRunner stops.

PHP client

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.

Installation

You can install the package via composer:

{% code %}

composer require spiral/roadrunner-services

{% endcode %}

Usage

To use the library, you need to create an instance of Spiral\RoadRunner\Services\Manager:

{% code title="app.php" %}

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'));

{% endcode %}

Create a service

To create a new service, use the create method:

{% code title="app.php" %}

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
}

{% endcode %}

Checking Service Status

To check the status of a service, use the statuses method:

{% code title="app.php" %}

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
}

{% endcode %}

Restarting a Service

To restart a service, use the restart method:

{% code title="app.php" %}

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
}

{% endcode %}

Terminating a Service

To terminate a service, use the terminate method:

{% code title="app.php" %}

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
}

{% endcode %}

{% hint style="info" %} When you're terminating the service, RR sends the SIGINT signal to the underlying process(ses). {% endhint %}

Listing All Services

To get a list of all services, use the list method:

{% code title="app.php" %}

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
}

{% endcode %}

API

Protobuf API

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.

• API