Worker Laravel Package

Technical Evaluation

What changed since the last assessment. The picture has moved from a single release to a short, active release cadence. v3.8.0 (2026-10-10) was the material one: the formal rename to roadrunner/worker, the PHP 8.2 floor, refreshed docs, and inert #[\Override] annotations. v3.8.2 (2026-10-19) — with a v3.8.1 in between that we have not reviewed — is a single-line bug fix: the worker now detects the RoadRunner version from the roadrunner/roadrunner package rather than from whatever source it used previously. That is a small change with a non-trivial implication: version detection has moved into the Composer dependency graph, which is a different trust boundary from the rr binary we actually ship in the image. The #[\Override] and docs changes remain cosmetic. Nothing here is a breaking change, and nothing alters the strategic call — but it sharpens the version-skew story and is worth folding into the runbook and CI checks.

Architecture fit. Unchanged in substance, now confirmed in both name and organisation. roadrunner/worker is not an application-level library — it is the PHP-side runtime that speaks the Goridge protocol to the RoadRunner (Go) server and drives the worker loop, turning a PHP script into a long-lived, request-consuming process. For a Laravel estate this is an implementation detail of the RoadRunner adapter, not something application code should reference. The architecture question remains indirect: do we want a persistent-worker execution model (RoadRunner/Octane/FrankenPHP) at all, and is RoadRunner the runtime we standardise on? The v3.8.2 fix, which reaches into a sibling roadrunner/* package for the server version, reinforces that this is infrastructure plumbing — the package now has opinions about its own deploy environment.

Integration feasibility. Feasible but indirect, and slightly more constrained than before. Laravel teams reach RoadRunner via Octane's RoadRunner driver or spiral/roadrunner-laravel/bridge packages, which pull this worker transitively. The rename introduces a genuine Composer identity problem: any bridge package that still requires spiral/roadrunner-worker will either conflict with, or install alongside, the new name — risking a duplicate vendor tree or an unresolvable dependency set. This must be resolved by the bridge maintainers, not by us. Added by v3.8.2: the worker now reads the server version from roadrunner/roadrunner, so we should establish whether that package is a genuine installable artifact (does it ship or pin the rr binary?) or merely version metadata. Either way it becomes a fifth thing to keep in lockstep, and one that Composer can silently satisfy with a version different from the binary on disk. Direct adoption still only makes sense if we are writing a custom worker bootstrap, which should be an explicit architecture decision. The package remains framework-agnostic (PSR-7/PSR-17 oriented), MIT-licensed, and small — the integration cost sits in the Go binary, the worker lifecycle, and now the version-detection contract.

Technical risk.

• PHP 8.2 floor (from v3.8.0). If any service in the estate is still on PHP 8.1, a transitive bump silently blocks composer update — or worse, resolves to an older pinned version and drifts from the rest of the fleet. Verify the floor against our actual minimum-supported PHP and against the Laravel version matrix before assuming this is free.
• Package rename (from v3.8.0). Renames are ecosystem churn events. Expect a window where bridge packages, SBOM/abandoned-package scanners, internal docs, and developer muscle memory reference the old name. Internal allowlists and vulnerability-scanner rules keyed on spiral/roadrunner-worker will need updating, otherwise the package drops out of our supply-chain visibility. v3.8.2 widens this: there are now at least three roadrunner/* names in play (roadrunner/worker, roadrunner/roadrunner, plus the legacy spiral/* name), so scanner rules should match on the vendor namespace, not a single package string.
• Version detection via Composer (new in v3.8.2). The worker infers the server version from a Composer package rather than from the running rr process. If roadrunner/roadrunner resolves to version X but the base image ships binary Y, the worker's compatibility assumptions are wrong in a way that is invisible until a protocol feature is used. Treat the package version and the binary version as a paired pin, verified in CI.
• Signals are weak. Small star count and 0 listed dependents are largely explained by this being a low-level, transitively-consumed component, and the old name was similarly invisible. Do not read 0 dependents as "unused," but do not treat it as battle-tested by proxy either. A rename typically resets adoption metrics, so the low numbers will persist for a while.
• Two-runtime stack. Shipping the rr binary alongside PHP adds a second versioned artifact to every image, with a protocol compatibility contract between binary and PHP worker — now mediated by a third artifact's declared version.
• State leakage. Persistent workers change the correctness model: singletons, static state, and open DB connections survive across requests. A security and data-integrity concern, not just a bug class.
• Maintenance concentration. Small maintainer base. Two releases in nine days (3.8.1 unreviewed, 3.8.2 a targeted fix) reads as active ownership rather than abandonment — mildly reassuring, and slightly better evidence than the single release we had before. Still a concentration risk.

Key questions.

1. Is this a rename/successor to spiral/roadrunner-worker? Answered: yes. Open follow-up: what is the EOL/abandonment timeline for the old name, and does it still receive security patches during the transition?
2. Which bridge/Octane versions declare support for the new package name, and is there a documented cut-over, or must we rely on Composer aliasing? Will an install today produce both names in vendor/?
3. (Revised) What is the compatibility contract between this package, the roadrunner/roadrunner package version, the actual rr binary version, and Laravel Octane's supported versions — and which of the four is authoritative when they disagree?
4. (New) Does roadrunner/roadrunner ship or pin the binary, or is it metadata only? If metadata, how do we guarantee the declared version matches the binary baked into the base image?
5. (New) What did v3.8.1 change? We have a gap in the release record between the rename and this fix, and it should be reviewed before we pin.
6. Does our minimum-supported PHP meet 8.2, and does every service's Laravel version support 8.2 cleanly — or does this bump force a framework upgrade in the same change?
7. Who maintains it (RoadRunner core team vs. community), what is the security disclosure process, and is there any LTS commitment?
8. What is the documented worker reset/isolation story, and does it satisfy our data-isolation requirements?

Integration Approach

Stack fit. RoadRunner targets throughput-sensitive, IO-bound HTTP APIs and queue-style services. It is a poor fit for teams relying on per-request globals, register_shutdown_function semantics, or extensions that assume process-per-request teardown. Laravel support via Octane is mature enough that the framework is not the constraint — the constraint is our application's hidden statefulness, plus our PHP version floor and, as of v3.8.2, how faithfully we pin the binary-to-package version pair.

Migration path. Do not adopt this package directly. Adopt it via Laravel Octane's RoadRunner driver (or the Spiral Laravel bridge), pin the transitive version explicitly in composer.lock, and treat the rr binary as a first-class pinned dependency in the base image. Treat the rename as a distinct, scheduled change rather than something that arrives with a routine composer update. Sequence it as (a) confirm bridge support for roadrunner/worker, (b) update internal allowlists, SBOM tooling and docs to the new vendor namespace, (c) verify only one of the two legacy names resolves into vendor/, (d) roll out with the base image, not per-service. Added for v3.8.2: pin roadrunner/roadrunner alongside the binary and assert in CI that the version the worker detects equals the version of the rr binary actually invoked.

Compatibility. Five axes must now be locked together: PHP minor (≥8.2), package name and version (roadrunner/worker vs. legacy spiral/roadrunner-worker), the bridge/Octane version, the roadrunner/roadrunner version used for detection, and the rr binary version. Add a CI check that boots the worker against the pinned binary and issues a real request — this catches protocol skew, duplicate-package resolution, and (new) version-detection mismatch before deploy. Consider having that check log the detected version and diff it against the binary's --version output. Confirm the PSR-7 implementation chosen by the bridge is consistent across services.

Sequencing.

1. Constraint check (days, not a sprint): confirm PHP 8.2 minimum across the fleet, confirm the bridge/Octane versions in use accept the renamed package, and review the skipped v3.8.1. Prerequisite, not a mid-pilot discovery.
2. Evaluate (1 sprint): benchmark one representative service under php-fpm vs. RoadRunner in staging; measure p50/p99 latency, throughput, and memory growth over a sustained soak.
3. Harden: audit the candidate service for static/singleton state, connection reuse, and request-scoped assumptions; add worker-reset hooks.
4. Pilot: run one non-critical, high-read service behind RoadRunner with php-fpm retained as a feature-flagged rollback at the ingress.
5. Standardise: publish a blessed base image and template rr.yaml; pin the binary and roadrunner/roadrunner together; make direct dependencies on the worker package a lint rule; update internal naming/SBOM references to the vendor namespace.
6. Expand: migrate additional services by fit, not by default.

Operational Impact

Maintenance. Low code-churn surface (a thin protocol/loop layer), but maintenance burden shifts to image and configuration management: the rr binary, rr.yaml, worker pool sizing, and PHP extension parity. The v3.8.2 release nudges a little of that burden back into Composer: the base image now has a declared-version package and a separate on-disk binary that must agree. Add a one-time housekeeping cost to retire the spiral/roadrunner-worker name from internal tooling, scanner exceptions, and developer documentation. Budget ongoing ownership for the base image and the version-pin pair, not for this library.

Support. No commercial support implied by an MIT package. Our support path is the Octane/bridge maintainers and the RoadRunner community channels. Given the low visibility signals, assume we are effectively self-supporting for edge cases and plan an internal owner (platform team) able to read the worker loop source — it is small enough that this is realistic. The rename and the recent cadence raise the value of that internal owner: we are more likely than the community to notice a broken bridge constraint or a detection mismatch first, because our install shapes differ from the maintainers'.

Scaling. RoadRunner scales well horizontally (more pods) and vertically (more workers per pod), but worker count must be tuned against memory: each worker is a full Laravel bootstrap. Set max_jobs and memory limits explicitly to force recycling before leaks accumulate. Autoscaling metrics change — CPU per pod rises while concurrency is handled in-process; HPA thresholds tuned for php-fpm will mis-fire.

Failure modes.

• Dependency-resolution failure from the rename (pre-production). Bridge pins on the old name block installs or produce a duplicate package. Manifests as a failed CI build or, worse, a silent downgrade — caught by the CI boot check, not by code review.
• Version-detection mismatch (new, v3.8.2). roadrunner/roadrunner resolves to a version that does not match the rr binary in the image, so the worker makes incorrect protocol assumptions. Manifests as intermittent, hard-to-attribute failures on specific features rather than a clean boot error — the worst kind of skew. Caught by asserting detected-vs-actual in CI.
• PHP floor mismatch (pre-production). A service on 8.1 either fails to update or freezes on an older worker version while the fleet moves, creating version drift.
• Loss of supply-chain visibility. Scanners and SBOM rules keyed to the old package name stop reporting on the new one; vulnerabilities go unseen. Match on the roadrunner/* namespace and fix at rename time, not later.
• Protocol/version skew between rr and the PHP worker → worker fails to boot or hangs; surfaces as ingress 502/504 with little PHP-side logging.
• Silent worker death from uncaught fatals or OOM → capacity degrades gradually; alert on healthy-worker count, not just request error rate.
• Memory growth across requests → eventual OOM kill; mitigated by max_jobs and soak testing, detected by per-worker RSS monitoring.
• State bleed between requests (auth context, locale, cached config) → correctness and potential data-exposure incidents; highest severity and hardest to detect in testing.
• Lost observability — $_SERVER-derived context, some profiling hooks, and per-request log correlation behave differently; validate tracing propagation early.
• Cold start — booting N workers on deploy creates a latency spike; requires readiness gating and rolling updates.

Ramp-up. Two to three weeks of genuine learning per team: worker lifecycle semantics, Goridge/RoadRunner config, debugging across the Go/PHP boundary, and local development parity (rr serve vs. artisan serve). The package itself is learnable in an afternoon. These releases add negligible ramp-up but do add Composer troubleshooting wrinkles worth a paragraph each in the runbook — "why is there a spiral/roadrunner-worker directory in vendor/?" and "why does the worker think the server is a different version?" will both be asked. Invest in a runbook and golden-path base image before the second team onboards.

Recommendation. v3.8.2 is a patch, not a pivot: a one-line fix that relocates server-version detection into the Composer graph. It changes no strategic conclusion. Continue to treat roadrunner/worker as infrastructure consumed transitively, never as a direct application dependency, and continue to gate adoption on a soak-tested pilot. Two additions to the prerequisite list: (1) treat roadrunner/roadrunner and the rr binary as a paired pin, verified in CI rather than assumed; (2) review the unreviewed v3.8.1 before committing to a version. The rename remains the larger operational item — it is still the case that failing to update name-keyed tooling turns the rename into a supply-chain blind spot rather than a footnote, and the growing family of roadrunner/* packages makes namespace-level scanner rules the safer configuration.