Workerman Bundle Laravel Package

Technical Evaluation

Architecture fit. Unchanged by v0.4.0. This is a Symfony bundle, not a Laravel package. It ships a Kernel-oriented runtime that boots a Symfony application inside a Workerman worker loop. Laravel's equivalent seam is the Octane worker contract (Laravel\Octane\Contracts\OperationTerminated / the Worker bootstrap), a different abstraction. There is no service provider, no config publish, no Laravel-facing API. Adopting this in a Laravel codebase means writing and owning a bridge layer — a custom Octane-style driver or a bespoke Workerman\Worker bootstrap that constructs Laravel's Application, handles request conversion, and manages the sandboxed container lifecycle. That bridge is the real deliverable, not the package.

Practical implication: the package is reference material and a dependency for its Workerman process-management and PSR-7/HttpFoundation glue, not a drop-in. Budget ~1–2 engineer-weeks for a spike and a hardened bridge, plus ongoing ownership. Nothing in v0.4.0 reduces that.

Integration feasibility. Low-to-moderate, still gated on a clear reason to move off the default. Laravel Octane already covers Swoole, RoadRunner, and FrankenPHP — all with first-party support. Workerman's genuine differentiators remain narrow but real: pure PHP with no C extension, Windows support, and a mature ecosystem (GatewayWorker, webman) for socket/long-connection workloads. If the ask is "HTTP request throughput," Octane's existing drivers win on fit and support. If the ask is "a persistent-connection/WebSocket tier in PHP without Swoole," this becomes interesting — but then you are probably reaching for Workerman directly, not this bundle.

What v0.4.0 changes. Two items, both incremental:

• Workerman 5 support. Positive maintenance signal — the maintainer is tracking the current major, which was the single most likely thing to strand this package. But it also means the bundle now spans a Workerman major-version transition (4→5 changed worker APIs, process management, and some event-loop semantics). During that window the upstream surface we depend on is more volatile than a stable pin. Expect the next few releases to contain fixups. Net: slightly better long-term viability, slightly higher short-term churn.
• reuse_port configuration option (SO_REUSEPORT). Lets multiple independent master processes bind the same listening port, which is directly relevant to two things we flagged as operational weaknesses: zero-dropped-request deploys and multi-pool scaling without a single master as a bottleneck. This is a real capability, not cosmetic. Caveats: it is Linux-kernel-dependent, requires consistent socket options across all listeners, and gives you kernel-level load distribution with no visibility from the application — uneven connection distribution becomes a debugging problem you own.

Neither item touches the core finding: the Laravel bridge is still ours to build and maintain.

Technical risk.

• Adoption signal is still weak. 29 stars, 0 dependents, composite score 0.175. No production evidence to borrow. Treat every behavior as unverified — including the new Workerman 5 path, which has essentially no field exposure yet.
• Bus factor. Effectively single-maintainer. The 2025-08-21 release cadence is encouraging but does not offset the absence of a contributor base.
• State leakage. Long-running workers require the Laravel sandbox (container flush, facade reset, config/request/log rebinding). Octane solves this; a hand-rolled bridge must reimplement it or inherit subtle, intermittent bugs.
• Extension/API drift. Coupling to internal Workerman APIs means upstream changes can break us with no security or deprecation notice — and we are now mid-major-transition.
• Failure opacity. Forked-worker failures produce non-obvious symptoms; without Octane's tooling (octane:status, event hooks, Telescope integration) observability is on us.
• New: SO_REUSEPORT semantics add a failure mode we did not previously carry — port-sharing conflicts and skewed connection distribution that are invisible at the app layer.

Key questions for the team.

1. What is the concrete driver — throughput, Windows support, avoiding a C extension, or a WebSocket/gateway requirement? If "throughput," stop and benchmark Octane+FrankenPHP first.
2. Are we willing to own a permanent fork or bridge with no upstream Laravel community? Who is the named owner?
3. Does any part of the stack rely on register_shutdown_function, exit, global state, or per-request static caches that assume a fresh process?
4. What is the exit criterion — a benchmark target, a Windows-deploy requirement, or a memory-stability SLA over N hours?
5. Is a security review of this dependency acceptable to our supply-chain policy at this adoption level?
6. New: Are we pinning Workerman 5 from the start, or pinning 4 and forking the compatibility shim? Do not run a floating constraint across a major boundary with a single-maintainer dependency.

Integration Approach

Stack fit. Poor out of the box, moderate with investment. The package assumes Symfony's kernel lifecycle; Laravel's is adjacent but not compatible. Expect to vendor or fork the HttpFoundation/PSR-7 conversion pieces and reimplement the kernel-boot logic against Illuminate\Foundation\Application.

Migration path. Do not attempt a wholesale runtime swap. Sequence it:

1. Benchmark, don't integrate. Stand up a throwaway Workerman worker that boots Laravel and serves one trivial route. Compare p50/p99 latency and memory-per-worker against the FPM baseline and against Octane+FrankenPHP on identical hardware. 3–5 day spike; answers most of the go/no-go question.
2. Isolate the workload. If the driver is WebSockets or long-lived connections, target that tier only — a dedicated Workerman process handling sockets and dispatching to the existing HTTP app. Avoids touching the request path and sidesteps most state-leak risk.
3. Bridge only if step 1 clears a hard threshold. Build the Laravel worker bootstrap behind a feature flag, run it on one low-risk service, keep FPM as the fallback deployable.
4. Generalize last. Only after a full quarter of stable operation should this become a default.

Compatibility. Verify PHP version constraints and ext-* requirements against our platform images before anything else — Workerman 5 raises the PHP floor relative to 4, so confirm our oldest in-support runtime still qualifies. Confirm the bundle's Workerman constraint is an explicit major pin and not a range. Check compatibility with our Laravel major, with Octane if co-installed, and with middleware that assumes $_SERVER/php://input semantics. Confirm behavior under our process supervisor (systemd vs. container tini) — Workerman manages its own master/worker tree and fights naive supervisors.

Where reuse_port fits. Treat it as a deploy-time and scaling lever, not an integration shortcut. If adopted: validate on our target kernel, confirm consistent socket options across every listener, and load-test for connection distribution skew before relying on it for zero-downtime reload. It does not remove the need for graceful-reload testing; it changes the shape of it.

Sequencing and gates. Gate 1: benchmark shows a measured win over Octane. Gate 2: bridge passes the existing integration suite with workers running 10k+ requests without memory growth, on a pinned Workerman 5. Gate 3: 30 days in a canary with no state-leak incidents. Gate 4 (only if reuse_port is used): documented zero-dropped-request deploy and measured distribution evenness. Each gate is a stop point.

Operational Impact

Maintenance. The dominant ongoing cost is not the dependency, it is our bridge. Assume we own it permanently and that upstream will not accept Laravel-specific PRs. Budget a standing few engineer-days per quarter for PHP/Laravel upgrades and Workerman API drift, plus a documented fork policy so the work survives team turnover. v0.4.0 is a genuine positive on this axis — the maintainer shipped a current-major upgrade rather than letting the package rot — but it does not transfer ownership of the Laravel-side integration to them.

Support. No commercial support, no meaningful community to escalate to. Escalation path is: our fork, then Workerman internals. Contrast with Octane, where failure modes are documented and searchable. This materially changes incident MTTR and should be stated plainly to whoever signs off. Note also that Workerman 5 failure modes are less represented in existing write-ups than 4.

Scaling. Workerman's model is fixed worker pools per process manager — scale by replica count or by count in worker config. Memory-per-worker is higher than FPM and does not shrink; a leak becomes an OOM kill rather than slow degradation. Horizontal scaling works normally behind a load balancer; sticky sessions needed if any in-process state is held. Cold-start of a pool is slower than FPM — factor into burst handling. reuse_port opens a second scaling topology (multiple independent masters on one port), which is useful but adds a layer of operational reasoning the team did not previously need.

Failure modes to instrument before launch.

• Silent worker death — master does not always surface a crashed worker as an alert. Heartbeat metric per worker, alert on gaps.
• Memory creep — per-worker RSS time series with an alert at a defined ceiling; enforce max_request recycling as a safety valve.
• State bleed — log a tenant/user identifier per request and alert on cross-request mismatch.
• Hung event loop — a blocking call stalls the entire worker; track p99 latency per worker, not just per service.
• Zombie processes on deploy — signal handling differences mean graceful reload requires explicit testing; validate zero-dropped-request deploys in staging.
• New: connection distribution skew — if reuse_port is enabled, track per-listener accept counts and alert on sustained imbalance; SO_REUSEPORT will not do this for you.

Ramp-up. Expect 2–3 weeks before an engineer is productive debugging this stack: Workerman's process model, fork/reload semantics, and the Laravel container sandbox are three overlapping mental models, and there is little Laravel-specific material to learn from. That cost is incurred by every future on-call engineer — the strongest argument for keeping this scoped to a single isolated tier if it is adopted at all.

Recommendation. Unchanged in direction. Default to no for the main HTTP tier — Octane's existing drivers dominate on fit, support, and risk. Evaluate only against a specific unmet requirement (Windows deployment, no-C-extension constraint, or a WebSocket/gateway tier), and only via the benchmark-first sequence above. v0.4.0 modestly improves the maintenance and deploy story and is the strongest signal yet that the package is alive; it does not change the economics of the bridge we would have to own. If the requirement is real, the honest framing for stakeholders remains: we are adopting Workerman and building a thin Laravel bridge, with this bundle as a partial reference — not we are adopting a package.