README

Valkyrja RoadRunner

RoadRunner persistent worker entry point for the Valkyrja PHP framework.

This integration bootstraps the Valkyrja application once at worker startup, then dispatches every incoming request to an isolated child container so request state never bleeds between requests. The result is the performance benefit of a persistent process without the state-contamination risks of naive long-running PHP.

Requirements

PHP 8.4+
RoadRunner with the HTTP plugin (spiral/roadrunner-http ^4.1.0)
An existing Valkyrja application

Installation

composer require valkyrja/roadrunner

Usage

Wire the RoadRunner entry point into your application's front controller:

// app/public/index.php
use Valkyrja\Application\Data\HttpConfig;
use Valkyrja\RoadRunner\RoadRunnerHttp;

RoadRunnerHttp::run(new HttpConfig(
    dir: __DIR__ . '/..',
));

run() bootstraps the application once when the worker process starts, then enters the RoadRunner request loop. Each request is handled in an isolated child container so state never bleeds between requests.

Customizing Bootstrap

Override bootstrapParentServices() to force-resolve services that are expensive to create and safe to share across requests:

use Valkyrja\Application\Kernel\Contract\ApplicationContract;
use Valkyrja\Http\Routing\Collection\Contract\CollectionContract;
use Valkyrja\RoadRunner\RoadRunnerHttp;

class App extends RoadRunnerHttp
{
    protected static function bootstrapParentServices(ApplicationContract $app): void
    {
        $container = $app->getContainer();
        $container->getSingleton(CollectionContract::class);
        $container->getSingleton(MyExpensiveSharedService::class);
    }
}

Worker Lifecycle

See the Valkyrja framework repository for a full explanation of the persistent worker lifecycle, the child container isolation model, and configuration options.

Related Integrations

Other persistent-worker runtime integrations for Valkyrja PHP:

OpenSwoole — persistent worker via the OpenSwoole extension
FrankenPHP — persistent worker via the FrankenPHP embedded runtime

Contributing

See CONTRIBUTING.md for the submission process and VOCABULARY.md for the terminology used across Valkyrja.

Security Issues

If you discover a security vulnerability, please follow our disclosure procedure.

License

Licensed under the MIT license. See LICENSE.md.

valkyrja / roadrunner

Maintainers

Package info

Statistics

Security