PHPackages                             valkyrja/roadrunner - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Framework](/categories/framework)
4. /
5. valkyrja/roadrunner

ActiveLibrary[Framework](/categories/framework)

valkyrja/roadrunner
===================

RoadRunner persistent worker entry point for the Valkyrja Framework.

v26.0.2(1mo ago)00MITPHPPHP >=8.4CI passing

Since Apr 17Pushed 1w agoCompare

[ Source](https://github.com/valkyrjaio/valkyrja-roadrunner-php)[ Packagist](https://packagist.org/packages/valkyrja/roadrunner)[ Docs](https://www.valkyrja.io)[ RSS](/packages/valkyrja-roadrunner/feed)WikiDiscussions 26.x Synced 1w ago

READMEChangelog (3)Dependencies (2)Versions (18)Used By (0)

[ ![](https://raw.githubusercontent.com/valkyrjaio/art/refs/heads/master/long-banner/orange/php.png)](https://valkyrja.io)

Valkyrja RoadRunner
===================

[](#valkyrja-roadrunner)

RoadRunner persistent worker entry point for the [Valkyrja](https://valkyrja.io)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.

 [![PHP Version Require](https://camo.githubusercontent.com/0b569874a42bd1c9245a4d9a0268b3b02fc266e9deffe1e15352d5009c3e9f7b/68747470733a2f2f706f7365722e707567782e6f72672f76616c6b79726a612f726f616472756e6e65722f726571756972652f706870)](https://packagist.org/packages/valkyrja/roadrunner) [![Latest Stable Version](https://camo.githubusercontent.com/debde16ce44b91ea0e15657d944da452313ea1daf34b55893d1e41dc75b914d8/68747470733a2f2f706f7365722e707567782e6f72672f76616c6b79726a612f726f616472756e6e65722f76)](https://packagist.org/packages/valkyrja/roadrunner) [![License](https://camo.githubusercontent.com/4113864036e8fdddf33b93593c856315227f5bbc65f54728b65e79a4caf5d4c8/68747470733a2f2f706f7365722e707567782e6f72672f76616c6b79726a612f726f616472756e6e65722f6c6963656e7365)](https://packagist.org/packages/valkyrja/roadrunner) [![CI Status](https://github.com/valkyrjaio/valkyrja-roadrunner-php/actions/workflows/ci.yml/badge.svg?branch=26.x)](https://github.com/valkyrjaio/valkyrja-roadrunner-php/actions/workflows/ci.yml?query=branch%3A26.x) [![Scrutinizer](https://camo.githubusercontent.com/a8a144d92371874fd640fa8a1c3d4553d9ecae52f04cd7c2fe8d13de1c93b2f4/68747470733a2f2f7363727574696e697a65722d63692e636f6d2f672f76616c6b79726a61696f2f76616c6b79726a612d726f616472756e6e65722d7068702f6261646765732f7175616c6974792d73636f72652e706e673f623d32362e78)](https://scrutinizer-ci.com/g/valkyrjaio/valkyrja-roadrunner-php/?branch=26.x) [![Coverage Status](https://camo.githubusercontent.com/75b5f62630c837754c90dac5857d5da56c82d2e0e49d81e38b064563da689611/68747470733a2f2f636f766572616c6c732e696f2f7265706f732f6769746875622f76616c6b79726a61696f2f76616c6b79726a612d726f616472756e6e65722d7068702f62616467652e7376673f6272616e63683d32362e78)](https://coveralls.io/github/valkyrjaio/valkyrja-roadrunner-php?branch=26.x) [![Psalm Shepherd](https://camo.githubusercontent.com/f5b819df5a51a9b1f3068af410b433ce454d6fc45081ea9779b64bebd0bf5a16/68747470733a2f2f73686570686572642e6465762f6769746875622f76616c6b79726a61696f2f76616c6b79726a612d726f616472756e6e65722d7068702f636f7665726167652e737667)](https://shepherd.dev/github/valkyrjaio/valkyrja-roadrunner-php) [![Maintainability Rating](https://camo.githubusercontent.com/8fb9d0bbec716edce3f2f98f3cd16435d4afefddd6d8647093534a8c85b73945/68747470733a2f2f736f6e6172636c6f75642e696f2f6170692f70726f6a6563745f6261646765732f6d6561737572653f70726f6a6563743d76616c6b79726a61696f5f726f616472756e6e6572266d65747269633d7371616c655f726174696e67)](https://sonarcloud.io/summary/new_code?id=valkyrjaio_roadrunner)

Requirements
------------

[](#requirements)

- PHP 8.4+
- [RoadRunner](https://docs.roadrunner.dev/docs/php-worker/worker) with the HTTP plugin (`spiral/roadrunner-http ^4.1.0`)
- An existing [Valkyrja](https://github.com/valkyrjaio/valkyrja-php) application

Installation
------------

[](#installation)

```
composer require valkyrja/roadrunner

```

Usage
-----

[](#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

[](#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
----------------

[](#worker-lifecycle)

See the [Valkyrja framework repository](https://github.com/valkyrjaio/valkyrja-php) for a full explanation of the persistent worker lifecycle, the child container isolation model, and configuration options.

Related Integrations
--------------------

[](#related-integrations)

Other persistent-worker runtime integrations for Valkyrja PHP:

- [**OpenSwoole**](https://github.com/valkyrjaio/valkyrja-openswoole-php) — persistent worker via the OpenSwoole extension
- [**FrankenPHP**](https://github.com/valkyrjaio/valkyrja-frankenphp-php) — persistent worker via the FrankenPHP embedded runtime

Contributing
------------

[](#contributing)

See [`CONTRIBUTING.md`](https://github.com/valkyrjaio/.github/blob/master/CONTRIBUTING.md) for the submission process and [`VOCABULARY.md`](https://github.com/valkyrjaio/.github/blob/master/VOCABULARY.md) for the terminology used across Valkyrja.

Security Issues
---------------

[](#security-issues)

If you discover a security vulnerability, please follow our [disclosure procedure](https://github.com/valkyrjaio/.github/blob/master/SECURITY.md).

License
-------

[](#license)

Licensed under the [MIT license](https://opensource.org/licenses/MIT). See [`LICENSE.md`](./LICENSE.md).

###  Health Score

43

—

FairBetter than 89% of packages

Maintenance94

Actively maintained with recent releases

Popularity0

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity60

Established project with proven stability

 Bus Factor1

Top contributor holds 69.5% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~11 days

Total

5

Last Release

8d ago

Major Versions

v1.0.0 → v26.0.02026-04-17

### Community

Maintainers

![](https://www.gravatar.com/avatar/fbb43a59fb790365b014e53f82e3f26893867e4a47a249fc92962b6dc76878f2?d=identicon)[MelechMizrachi](/maintainers/MelechMizrachi)

---

Top Contributors

[![valkyrja-volundr[bot]](https://avatars.githubusercontent.com/in/2462900?v=4)](https://github.com/valkyrja-volundr[bot] "valkyrja-volundr[bot] (57 commits)")[![MelechMizrachi](https://avatars.githubusercontent.com/u/1179171?v=4)](https://github.com/MelechMizrachi "MelechMizrachi (25 commits)")

---

Tags

frameworkroadrunnerworkervalkyrja

### Embed Badge

![Health badge](/badges/valkyrja-roadrunner/health.svg)

```
[![Health](https://phpackages.com/badges/valkyrja-roadrunner/health.svg)](https://phpackages.com/packages/valkyrja-roadrunner)
```

###  Alternatives

[pestphp/pest-plugin-stressless

Stressless plugin for Pest

68943.9k18](/packages/pestphp-pest-plugin-stressless)[yiisoft/yii-runner-roadrunner

Web application runner for RoadRunner

3410.9k](/packages/yiisoft-yii-runner-roadrunner)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)