Search by

sailantis / spiral-volucer

lumielis

Run a Spiral application on volucer's persistent worker protocol.

Package info

github.com/sailantis/spiral-volucer

pkg:composer/sailantis/spiral-volucer

Statistics

Installs: 1

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

v0.4.2 2026-11-16 02:43 UTC

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. RESPONSE declares body_len before the body, so a response is complete before it starts.
  • multipart/form-data uploads. See above.