Worker Laravel Package

Product Decisions This Supports

• Build vs. buy on the runtime layer. This package is the seam between your PHP code and the RoadRunner Go server: it owns the worker loop, payload waiting, response/error framing, and worker lifecycle hooks. The decision it informs is not "should we use this class" but "should we standardize on RoadRunner as our PHP application server instead of PHP-FPM or Swoole." That is a real roadmap-level decision with performance, ops, and hiring implications.
• New worker types = new product surfaces. If the roadmap includes long-running background consumers, internal RPC over TCP, streaming/SSE endpoints, or CPU-heavy pools, this is the base class you extend. Each of those is a feature-level decision ("can we ship realtime updates without adding a Node service?") that hinges on whether you can cheaply build a custom worker.
• Scope containment. It does not give you routing, PSR-7 message implementation, middleware, or framework integration — those live in sibling packages (spiral/roadrunner-http, spiral/roadrunner-laravel, etc.). A PM reading this as a "framework" will over-scope. Correct framing: it is ~1 of 5 packages you actually adopt; it is the piece that makes the others possible.
• Performance and cost roadmap. Persistent workers eliminate per-request bootstrap. This package's loop is where that win is realized, so it is the item to cite when justifying an "upgrade the runtime" initiative against infra spend or p99 latency targets.
• Platform currency (new in 3.8.0). The package now requires PHP 8.2. That converts an invisible dependency into a roadmap constraint: any application still on 8.0/8.1 is frozen at v3.7.x, which is now a dead branch receiving no fixes. If a service is pinned there, "upgrade PHP" is no longer hygiene work — it is a prerequisite for security patching on the runtime layer, and should be sequenced explicitly.
• Risk/exit decision. MIT, small public API, no Go required on your side. It is forkable and swappable, which lowers the political cost of committing to RoadRunner. That is a genuine input to a buy/adopt decision. Note the 3.8.0 rename (spiral/roadrunner-worker → roadrunner/worker) also signals the ecosystem consolidating under the roadrunner org — good for longevity, but it means the old package name is on a path to abandonment, so "stay on the old name" is not a stable holding position for security-patch purposes.
• Migration cost line item. The rename is a composer.json constraint change plus lockfile churn, not a code rewrite; namespace stays Spiral\RoadRunner. For direct consumers this is an afternoon. For transitive consumers it is a dependency-resolution check, not a project. Budget accordingly — do not let it get scoped as an initiative.

Metric caveat for the decision record: 22 stars and 0 dependents understate it badly. It is consumed transitively through the spiral/roadrunner-* family and framework integrations, not directly by applications. Before citing adoption in any decision doc, pull Packagist download numbers for the parent packages — the GitHub signals here measure nothing useful. The same applies to the rename: early download counts on roadrunner/worker will look tiny and mean nothing; the signal is whether the framework integrations repoint their constraints.

When to Consider This Package

Adopt (usually transitively, occasionally directly) when all of these hold:

• You have committed to, or are seriously piloting, RoadRunner as the application server.
• You need a worker that is not plain HTTP request/response — queue consumer, custom protocol, streaming endpoint, internal service.
• You want explicit control over payload handling, error propagation, and shutdown behavior rather than a framework's opinion.
• Someone on the team owns long-running process operations: memory growth, fatal-error recovery, pool sizing, supervisor config.
• Your application runtime is PHP 8.2+ (hard requirement as of 3.8.0).

Look elsewhere when:

• You are building a standard Laravel web app. Use laravel/octane or spiral/roadrunner-laravel. Touching this package directly is a smell, and it adds a maintenance surface for zero product value.
• You are not on RoadRunner. Adopting the worker base without the server is incoherent; start with the server decision.
• The problem is already solved above you. Background jobs = Horizon/Redis/SQS. Realtime = a managed service. Building a custom worker to replicate these is a classic PM trap: it looks cheap because the base class is small, and it is not.
• No appetite for persistent-process ops. Long-running PHP workers change your failure model (leaks accumulate, one crash can take a pool member). If nobody owns that, stay on FPM.
• You are stuck below PHP 8.2. v3.7.x is the terminal branch; adopting now means adopting an already-frozen release. Fix the platform floor first.
• You need vendor support or SLAs. No commercial backing here; MIT means you can fork, which also means you own your forks.

How to Pitch It (Stakeholders)

To executives: This is not a feature — it is plumbing that comes free with a runtime choice. The decision on the table is adopting RoadRunner, and this package is the small, MIT-licensed component that lets our PHP code talk to it. No new vendor, no license cost, no lock-in: the API surface is small enough to replace, and the recent rename is a packaging change, not a re-platforming event. The upside is measurable — removing per-request bootstrap improves latency and reduces CPU per request; the cost is operational discipline around long-running processes, which we either already have or must fund. The one new ask is a PHP 8.2 floor, which is a prerequisite rather than a trade-off.

To engineering: Treat this as an internal dependency, not a library to design around. Consume it through the framework integration; extend the base worker only for worker types the framework doesn't cover. In 3.8.0 the package moved to roadrunner/worker and now requires PHP 8.2 — update your composer constraint, verify the sibling spiral/roadrunner-* packages have repointed to the new name before dropping the old one, and don't be surprised by the #[\Override] annotations if you subclass (they'll fail loudly on a bad signature, which is the point). Pin the version, keep the surface area minimal, and write one integration test that proves shutdown and error paths behave under the supervisor. If we extend it, that code is ours to maintain — budget for it explicitly.

Recommendation: Adopt as a transitive dependency alongside the RoadRunner decision; do not adopt as a standalone initiative. Action the 3.8.0 upgrade as routine maintenance (constraint rename + PHP 8.2 floor), tracking it as a dependency-currency task, not a project. Re-evaluate the strategic position only if we commit to a custom worker type, at which point scope it as a small, time-boxed engineering spike with a documented fallback.