Reactor Laravel Package

Technical Evaluation

Scope and architecture fit. windwalker/reactor sits in the Windwalker family of decoupled PHP packages. As the name implies, it targets the Reactor pattern — an event-loop / async-dispatch abstraction rather than a data-layer or utility library. That framing matters for Laravel: Laravel's HTTP lifecycle is synchronous and shared-nothing, so a reactor has no place in the request path. Its only viable home is in long-lived processes — queue workers, daemons, CLI supervisors, websocket servers — where an event loop already exists (Swoole/RoadRunner via Octane, or a standalone ReactPHP loop). Fit is therefore narrow but non-zero: real for teams running async workers, irrelevant for standard CRUD apps.

Integration feasibility. It is a Composer/PSR-4 package with no Laravel service provider, facade, or config publish. Any adoption means writing our own bridge: a container binding, a lifecycle hook to start/stop the loop, and error translation into Laravel's exception handler and logger. That is a day of glue work, not a blocker — but it is code we own forever.

Technical risk. This is the dominant concern and it is severe:

Add to that unknown PHP version constraints, an unclear security-disclosure path, and abandonment risk with no fork community to inherit the code. For a TPM, the expected-value calculation is simple: the capability overlaps with primitives we already have (Laravel queues, Illuminate\Bus batches, Octane, ReactPHP directly), so we are taking on maintenance liability for something we could otherwise get from a maintained vendor.

Key questions to close before any commitment.

1. What does this do that react/event-loop, react/promise, Laravel Horizon, or Octane does not already cover for us?
2. What is the last release date, commit cadence, and open-issue count? Is there a tagged version and a BC policy?
3. Which PHP versions and extensions (ext-swoole, ext-uv, none) does it require or support?
4. License and CLA — is forking and vendoring legally clean?
5. Test coverage and CI status — can we trust the behaviour we cannot see?
6. Does it hold global/static state that would leak across requests in a persistent worker?

Verdict: treat as evaluate-only, not adopt until question 1 has a concrete, specific answer that our existing stack cannot satisfy.

Integration Approach

Stack fit. Only pursue if we already run an async runtime or have a validated need for one (e.g. hundreds of concurrent outbound HTTP calls per job). In a vanilla Laravel app behind PHP-FPM, this package buys nothing and costs a dependency.

Architecture pattern — build a port, not a dependency. Rather than importing the package into domain code, define our own narrow interface (something like EventDispatcher/LoopRunner) in application space and implement it with an adapter. If the package is abandoned or a better option appears, we swap the adapter and delete one file. This also makes the spike reversible, which is the main thing a TPM needs from an experiment on a 0-star library.

Migration path.

1. Spike (1 week): install in a throwaway branch, wrap in the adapter, run one non-critical queue worker against it.
2. Harden: fork to our GitHub org or private Packagist, pin the exact commit, add Dependabot and a CI job that runs the package's own tests plus our adapter tests.
3. Shadow: run the async path alongside the existing synchronous implementation on a sampled workload; compare latency, memory, and error rates.
4. Cut over one workload, with a feature flag to revert to dispatch() / the queue driver.
5. Decide: keep, replace with ReactPHP directly, or delete.

Compatibility checks. Confirm Laravel 10/11 and PHP 8.1+ support in composer.json; watch for conflicts with Octane's loop, Swoole coroutine hooks, and any package that assumes a fresh process per request (static caches, once() helpers, container singletons mutated per-request). Composer constraint drift is the likeliest source of a surprise break.

Sequencing rationale. Compatibility and license verification must precede engineering effort — spending two sprints on glue for a package we cannot legally fork or that does not support our PHP version is the classic sunk-cost trap.

Operational Impact

Maintenance becomes an internal line item. With no external contributors, we are the de facto maintainers: reviewing the source ourselves, patching PHP-version breakage, and carrying a fork. Budget roughly 10–15% of one engineer's capacity ongoing. If that is not fundable, the answer is no.

Support model. There is no vendor, no SLA, and no community forum. We must name an internal owner, document a runbook (how the loop starts/stops, how to diagnose a hung worker), and accept that incidents route to us first. Incident tooling — Sentry/OpenTelemetry integration, structured logging — has to be wired manually into the loop.

Scaling characteristics. Async only pays off for I/O-bound work. CPU-bound jobs will perform worse than the standard queue, because a single blocked call stalls the whole loop. Long-lived workers also change the memory profile: leaks that a per-request model masks become fatal over hours, so we need worker recycling (max_jobs-style restarts) and per-worker memory alerting from day one.

Failure modes to instrument for.

• Unhandled promise rejections — silently dropped work, no error surfaced.
• Loop starvation from a single blocking call (DB driver, file_get_contents, synchronous HTTP).
• Memory growth in persistent workers; container singleton accumulation.
• Static-state bleed between tasks in a reused process — data leakage risk, not just a bug.
• Shutdown hangs: in-flight tasks ignored on deploy/SIGTERM, producing duplicate or lost jobs.

Ramp-up. This is a genuine skill investment, not a library install. Engineers need the reactor mental model — non-blocking discipline, promise composition, cancellation. Expect one to two sprints before a mid-level engineer is productive and compliant with the "never block the loop" rule, and expect code review overhead permanently. Compare that to the near-zero ramp-up of dispatch() and the existing queue worker.

Bottom line for planning. Opportunity is low, risk is high, and the capability is largely substitutable. The rational TPM position is a time-boxed spike behind an adapter interface, with an explicit exit criterion and an assumed default of building or buying elsewhere. Do not let this enter a critical path until it has earned it.