Cluster Laravel Package

Technical Evaluation

Architecture fit. amphp/cluster is not a Laravel package in any conventional sense — it ships no service provider, facade, config stub, or publishable assets. It is a process-supervision and socket-sharing primitive for applications already built on the AMPHP/Revolt asynchronous stack, letting a PHP CLI program fork N worker processes that each run an event loop and (where the OS supports it) bind the same listening socket via SO_REUSEPORT. Laravel's request lifecycle is the opposite shape: a synchronous, blocking, boot-per-request kernel built around FPM-style process recycling. Dropping this package into a Laravel app accomplishes nothing; adopting it means replacing the serving layer and accepting async constraints throughout the code path. Fit is therefore low for the main application and moderate only for a narrowly scoped, dedicated daemon (a socket server, websocket fan-out, or internal TCP service) that happens to live in the same monorepo.

Integration feasibility. Feasible but bespoke. The realistic integration is a hand-written entrypoint script that boots the Laravel container inside each cluster worker, plus custom work to reset scoped bindings, reconnect database/Redis pools, and handle signals between requests. None of that is provided. Every blocking call — PDO, file I/O, most of the Guzzle/cURL stack, sleep, mail transport — stalls the worker's loop and therefore every request assigned to it. Making Laravel safe under this model is essentially re-implementing what Laravel Octane already does, without Octane's worker-lifecycle events, sandboxing, or ecosystem familiarity.

Technical risk. High, on several independent axes:

• Ecosystem maturity. 61 stars and a low opportunity score (1.51 against a 2.26 composite) signal a thin adoption base. The AMPHP v2→v3 transition (Revolt event loop) was a breaking rewrite; expect further churn before a stable 1.0 contract.
• Platform constraints. SO_REUSEPORT and POSIX signal handling mean this is a Linux/macOS story; Windows developers cannot run the production topology locally, creating a dev/prod parity gap.
• Debuggability. Each worker is a separate PID with its own loop and memory space. Stack traces, dd(), Telescope, and most APM agents assume a single request-scoped process.
• Failure semantics. Supervising, restarting, and draining workers gracefully is the package's job, but the integration's correctness (stale container state, leaked singletons, half-open DB connections) is ours.
• Competing loop owners. It cannot coexist in-process with Swoole or RoadRunner; picking it forecloses Octane.

Key questions to answer before any commitment.

1. What is the actual workload — front-door HTTP, or a background/daemon service? If HTTP, why is Octane (Swoole, RoadRunner, or FrankenPHP) insufficient?
2. Is there a hard requirement for pure-PHP, no-extension serving that only AMPHP satisfies?
3. Who owns the entrypoint, worker lifecycle, and production runbooks — us or the vendor?
4. What is the support and release policy? Is there a credible path to 1.0 and an LTS?
5. Do we have in-house AMPHP/fiber competence, or is this a hiring problem?
6. Does the deployment target guarantee ext-sockets/ext-posix, kernel SO_REUSEPORT, and a Linux-only CI matrix?
7. What is the acceptable blast radius if a single blocking call degrades one worker's entire request cohort?

Integration Approach

Stack fit. Poor as a Laravel runtime, acceptable as an adjacent service. The defensible pattern is to keep Laravel on FPM or Octane for all business logic and HTTP, and use amphp/cluster only for a bounded, stateless, I/O-bound daemon that communicates over Redis, a queue, or an internal HTTP/gRPC boundary. Do not attempt to serve Laravel routes through it as a first move.

Migration path. Three staged options, in increasing cost:

1. Status quo plus Octane. If the driver is multi-core utilization or reduced boot overhead, Octane with Swoole/RoadRunner/FrankenPHP delivers it with supported worker lifecycle, warm-container semantics, and existing Laravel documentation. This should be the default answer.
2. Sidecar daemon. Build the async service as its own deployable artifact — its own Dockerfile, its own process supervisor, its own scaling policy — and integrate through a queue or HTTP. Laravel remains untouched.
3. Laravel-in-worker. Only if 1 and 2 are genuinely ruled out. This is a research project, not an integration: custom entrypoint, container reset logic, blocking-call audit, and a written list of forbidden APIs.

Compatibility. Requires a modern PHP (8.1+ for the current major) and pulls in revolt/event-loop, amphp/socket, amphp/process, and amphp/sync. Composer resolution against Laravel is unlikely to conflict — the AMPHP packages are framework-agnostic — but the runtime conflicts are the real constraint: no Swoole in the same process, no blocking extensions on the hot path, and POSIX-only execution. Verify OPcache/preload behavior across the master and forked workers early; mismatches surface as bizarre, intermittent runtime errors.

Sequencing.

1. Spike (2–3 weeks). One non-critical daemon, one Linux target, a load test that includes a deliberately blocking call to observe degradation. Success criteria defined up front.
2. Hardening harness. Crash/restart tests, 72-hour soak for memory growth, graceful-shutdown test under load, DB connection-count audit.
3. Operationalize. Containerize as a separate service; add per-PID metrics, structured logs with worker ID, and a runbook.
4. Re-evaluate. Only after all of the above should front-door HTTP be considered — and at that point the honest comparison is Octane, not this package.

Operational Impact

Maintenance. We inherit the integration glue permanently. Expect to pin exact versions, review every AMPHP release manually, and absorb breaking changes in the Revolt migration cycle. The upstream bus factor is the dominant long-term risk: a small maintainer set and a modest user base mean a stalled release or a security fix we must backport ourselves. Budget real engineering time, not a fraction of an FTE.

Support. Community-only. No vendor SLA, no commercial escalation path, and a shallow pool of engineers who have operated AMPHP clusters in production. Internal expertise is the support plan, which means at least two people must be trained, not one.

Scaling. Vertical scaling is the package's actual value proposition: N workers across N cores with kernel-level load balancing. Horizontal scaling still means more containers, so this is not a substitute for a scaling strategy. Three cost multipliers matter: each worker carries a full framework bootstrap in memory (N × Laravel footprint), each worker opens its own DB/Redis connections (pool size × workers), and per-worker state means sessions and caches must be externalized. Capacity planning must be redone from scratch rather than extrapolated from FPM numbers.

Failure modes. The recurring ones: a single blocking call stalling an entire worker's request cohort with no error, only latency; slow memory growth in long-lived workers that never surfaces in staging; ungraceful shutdown dropping in-flight requests on deploy; workers failing to rebind after a restart; connection-pool exhaustion as worker count grows; and silent divergence where a bug reproduces on one PID and not others. Standard tooling — Telescope, request-scoped logging, most APM agents — does not span processes, so observability has to be built per-worker before go-live, not after the first incident.

Ramp-up. Steep. The team needs fluency in futures/promises, fibers, non-blocking I/O discipline, and multi-process debugging — roughly four to eight weeks to working competence and considerably longer to on-call confidence. The failure mode of getting this wrong is not a crash; it is intermittent, hard-to-reproduce latency that erodes trust in the platform. That asymmetry, combined with the maturity signals, argues for keeping amphp/cluster out of the critical path and revisiting only if a concrete workload proves Octane and a sidecar service cannot serve it.