README

lsr/roadrunner connects the LSR application runtime to RoadRunner HTTP and jobs workers. It provides Nette DI wiring, HTTP error handlers, task production and payload serialization under the Lsr\Roadrunner\ namespace.

Requirements

PHP >=8.4 with fileinfo, gettext, simplexml, ctype, mbstring and pdo_sqlite.
LSR Core and Routing ^0.3 || ^0.4 || ^0.5, Interfaces ^0.3.5, and the Logging, Request, DB, Serializer, Cache and ORM ^0.3 packages.
Nette DI ^3.2, Latte ^3.0, Nette PHP Generator ^4.1 and phpdotenv ^5.6.
RoadRunner ^2025, worker ^3.6, HTTP ^4.1 and jobs ^4.6 PHP packages.
A running RoadRunner server with the appropriate plugins, RPC endpoint and job pipeline configured outside this library. The application must bootstrap LSR Core, including its services, runtime paths, session and translations.

Installation

composer require lsr/roadrunner

Runtime integration

extensions:
    roadrunner: Lsr\Roadrunner\DI\RoadrunnerExtension

roadrunner:
    rpc:
        host: tcp://localhost
        port: 6001
    jobs:
        queue: tasks

The RPC address and tasks queue must match the application's RoadRunner configuration. These settings connect PHP to an existing server; they do not create a RoadRunner configuration or provision a broker.

Configure RoadRunner to launch the application's PHP worker bootstrap. After initializing Core and its DI container, that bootstrap resolves Lsr\Roadrunner\Server and calls run(). The server reads RoadRunner's environment mode and selects the configured HTTP or jobs worker; invoking it as an ordinary CLI command without the RoadRunner environment is not a substitute for starting the server.

The default worker map is defined in RoadrunnerExtension. Custom workers implement Lsr\Roadrunner\Workers\Worker and can replace entries through the workers configuration map.

The HTTP worker converts incoming PSR requests using the application's Lsr\Interfaces\RequestFactoryInterface. The factory must return an LSR RequestInterface; the worker then sets that request on App and runs the application. The worker is long-lived, so application services must not assume that a new PHP process is created for every request. ORM instance caches are cleared between handled requests/tasks, but that does not reset arbitrary application state.

Background tasks

The task name is the DI service name of its dispatcher, not an arbitrary event label:

Implement TaskDispatcherInterface. getDiName() returns the registered service name; process() accepts the received RoadRunner task and an optional TaskPayloadInterface payload.
Register that dispatcher in the same application container used by jobs workers.
Inject TaskProducer and call push(DispatcherClass::class, $payload) for immediate dispatch. Use plan() followed by dispatch() to dispatch a batch. Optional RoadRunner job options can be passed to push() or plan().
The jobs worker resolves the dispatcher by service name and deserializes a nonempty payload. Successful processing is acknowledged if the dispatcher has not already completed the task; failures are negatively acknowledged and logged.

This package does not define the application's retry or dead-letter policy. Configure those policies in the chosen RoadRunner pipeline and make tasks safe to execute more than once.

Payload safety and serializer configuration

The default PhpTaskSerializer uses PHP unserialize() with classes allowed. Only trusted producers may submit payloads to queues consumed by this serializer. Do not expose such queues to untrusted input.

Producer and consumer must use compatible serializers and have the same payload classes available. The extension's jobs.serializer setting selects the producer serializer, while the jobs worker receives TaskSerializerInterface by autowiring. When overriding serialization, configure both sides consistently rather than changing only the producer option. Additional implementations are in src/Tasks/Serializers.

Request, worker, task-consumption and task-dispatch lifecycle hooks are available for instrumentation; their contracts are in src/Lifecycle.

Development

GitHub Actions runs CS, PHPStan and PHPUnit on PHP 8.4 and 8.5. Run the same checks locally:

composer install --prefer-dist --no-interaction --no-progress
composer cs
vendor/bin/phpstan analyse --no-progress
vendor/bin/phpunit --no-coverage

composer cs checks coding style without changing files. Run composer cs:fix (or composer cbf) to apply PHP CS Fixer rules from .php-cs-fixer.php.

The development manifest requires PHPUnit ^13; use a current PHP patch release that satisfies its platform requirements. The lifecycle tests use in-process doubles and do not require a running RoadRunner server, Redis or MySQL. CI runs without a coverage driver.

AI coding assistance

See LSR Skills for AI agent skills for working with the LSR framework.

License

Licensed under the MIT License.

lsr / roadrunner

Package info

Security

Statistics