sailantis / spiral-volucer
Run a Spiral application on volucer's persistent worker protocol.
Requires
- php: >=8.2
- nyholm/psr7: ^1.8
- sailantis/volucer-worker: ^0.4.2
- spiral/framework: ^3.14
Requires (Dev)
- phpunit/phpunit: ^10.5
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-16 02:58:30 UTC
README
Run a Spiral application on volucer's persistent worker protocol.
Why Spiral first
Of the three PHP frameworks the plan names, Spiral is the one a worker fits closest — and for a
reason that is a feature rather than an accident: ContainerInterface::runScope() is exactly the
per-request isolation primitive the protocol asks for. Everything created inside a scope — the
PSR-7 request, its bindings, every resolved instance — is discarded when the scope ends, and the
outer container keeps only what is genuinely application-scoped.
That is not a coincidence: RoadRunner support is why the scope exists. So this bridge does not invent a reset. It runs your existing dispatcher inside a scope and lets the framework do the thing it was built to do.
Install
composer require sailantis/spiral-volucer
Use
The entry point is the whole of it:
<?php // app.php — the worker entry point use Sailantis\SpiralVolucer\WorkerRunner; use Spiral\Framework\Kernel; use Spiral\Http\Http; require __DIR__ . '/vendor/autoload.php'; $app = Kernel::create( directories: ['root' => __DIR__], drivers: [], // your bootloaders )->build(); $container = $app->getContainer(); (new WorkerRunner($container->get(Http::class), $container))->run();
Point a backend at it:
[backends.spiral] kind = "worker" command = "php app.php" workers = 8
run() calls Worker::connect(), so VOLUCER_WORKER_SOCKET is honoured and stdio is the
fallback — the call a worker entry point must make, because Worker::create() would hang on the
socket transport.
What the bridge does, and what it deliberately does not
Scope name is http |
Spiral declares its HTTP services #[Scope('http')] — CurrentRequest among them. A differently named scope would still isolate the request, but CurrentRequest would resolve to the root's unset instance and middleware reading "the current request" would see null. |
| PSR-7 request is bound into the scope | So a service that type-hints ServerRequestInterface resolves the request being served rather than failing to autowire. |
| Superglobals are populated | Spiral's session and CSRF middleware, and several community packages, read $_SERVER and $_COOKIE directly rather than through the PSR-7 request. Both are filled before the dispatch and cleared after it. |
$_POST is parsed for application/x-www-form-urlencoded only |
A worker's body is bytes on the wire; nothing parses it for you. multipart/form-data is deliberately not parsed — the server has consumed the request, so a truncated file set would be worse than none. Uploads want the upstream backend. |
Cookies come from the Cookie header |
A PSR-7 request has no cookie params unless something parses them, and without it every request looks like a client's first. |
| The outer container is untouched | That is the point of the worker model: warm singletons are what the deployment is buying. Only what the scope created goes away. |
Tests
composer test
15 tests. Two drive a real volucer binary with a real worker process, because the things that
can go wrong — a scope that was never used, a socket transport that was never connected — are
exactly what a self-consistent fixture cannot see.
They skip without a binary and are found at VOLUCER_BIN or in ../volucer/target/debug/volucer.
VOLUCER_E2E=1 makes a skip a failure, which is what CI sets.
What this bridge does not do
- Multiplexed or async requests. The channel carries one request at a time, so concurrency is
workers— one process per worker. A protocol property, not an adapter gap. - Streamed responses.
RESPONSEdeclaresbody_lenbefore the body, so a response is complete before it starts. multipart/form-datauploads. See above.