Workerman Bundle Laravel Package

Technical Evaluation

Architecture fit. The package is a Symfony bundle (CrazyGoat\WorkermanBundle), not a Laravel package. It registers via config/bundles.php, ships Symfony console commands, a Symfony Configuration tree, compiler passes, and relies on Symfony's services_resetter and kernel lifecycle. For a Laravel estate there is no integration path without a rewrite: Laravel has no bundle/kernel-terminate equivalent, no services_resetter, and no Symfony DI tree to hook. The realistic TPM framing is therefore two-track:

1. Direct adoption — viable only for Symfony services in the portfolio (^6.4 | ^7.0 | ^8.0, PHP ^8.2).
2. Pattern harvesting — the underlying thesis (replace php-fpm + nginx + cron + supervisord with one pure-PHP Workerman process tree) is directly comparable to Laravel Octane + a scheduler + Horizon/Supervisor, so this repo is best used as a reference architecture and risk checklist, not a dependency.

The architecture itself is coherent: a middleware pipeline (MiddlewareInterface, StaticFilesMiddleware, SymfonyController) built once and cached, response conversion via a strategy pattern (BinaryFileResponse, StreamedResponse, chunked default), a SchedulerWorker and SupervisorWorker, plus console lifecycle management (workerman:server start/stop/restart/reload/status/connections) and PHAR/bin packaging. That is a genuine four-component consolidation, not a thin wrapper.

Integration feasibility. High for a Symfony service, low for anything else. Concrete gates:

The symlink rejection is a real deployment blocker: Kubernetes secret mounts are symlinks, so in-cluster TLS termination with this bundle will fail — TLS must sit at ingress/LB.

Technical risk. Ranked:

• Vendor/provenance risk (highest). 2 stars, 0 dependents, single fork lineage off luzrain/workerman-bundle. No commercial support, no production references, no evidence of third-party adoption. The release metadata (2026-10-06) should be verified against the actual tag/artifact before any decision.
• Fork divergence. The fork removes the PSR-7 pipeline and rewrites config loading, exceptions, and process supervision relative to upstream. Upstream security fixes will not arrive automatically; someone must own merge triage. The UPGRADE.md + changelog discipline exists but is self-imposed.
• Long-running state leakage. Correctness depends on services_resetter firing after kernel termination. Any service holding request state (identity, entity manager, buffers, static caches) will leak across requests. This is the classic Octane-class failure and it is not fully solved — it is delegated to Symfony's resetter coverage.
• Event-loop blocking. One synchronous DB call, HTTP client call, or sleep() serializes an entire worker. There is no documented blocking-I/O audit tooling.
• Documented footgun. static_files.allowed_extensions is silently ignored when StaticFilesMiddleware is registered as a service — which is exactly the recommended setup. Silent security-relevant config no-ops are a red flag for review rigor.
• Silent no-traffic failure. Omitting listen produces a worker that accepts no connections with no error. Same class of problem.
• Maturity signals are good but narrow: PHPStan level 8, Rector, PHP-CS-Fixer, 80% coverage floor, CI matrix PHP 8.2–8.5 × Symfony 6.4–8.1, unit + integration + e2e, 21-class exception hierarchy. Engineering quality is above what the star count implies; adoption evidence is what's missing.

Key questions.

1. Do we actually run Symfony services, or is this being evaluated for a Laravel estate? If Laravel, why this over Octane (RoadRunner/Swoole/FrankenPHP)?
2. Who owns the fork upstream-sync, and what is the CVE/patch SLA we'd be accepting?
3. What are measured p50/p95/p99 latency and memory-per-RPS versus our current fpm+nginx baseline on our workload?
4. How do we achieve zero-downtime deploys — reuse_port, graceful workerman:server reload, LB connection draining?
5. Which of our services are stateful, and does the resetter cover them? What is the audit method?
6. What is the observability plan for access logs, APM, and tracing inside the event loop?
7. Do we keep a CDN/edge for static assets, or serve them from PHP?
8. Security parity sign-off: who verifies trusted_hosts, blocked extensions, dot-file blocking, traversal protection, and symlink policy against our existing nginx ruleset?

Integration Approach

Stack fit. For Symfony: strong fit, drop-in via Composer + bundles.php + a workerman.yaml, minimal code change. For Laravel: not a fit as a dependency — treat it as a design reference and cost the equivalent build against Octane, or a thin Laravel adapter over Workerman (middleware pipeline, kernel handling, per-request flush, Artisan commands for lifecycle). Budget that adapter as net-new work with no upstream support.

Migration path. Phase it, one service at a time, behind the existing load balancer:

1. Baseline & gates — capture latency/memory/error-rate for the target service on fpm+nginx; confirm PHP/Symfony versions, pcntl/posix, and that TLS is terminated upstream.
2. Pilot one stateless HTTP service on an unprivileged port (8080) behind the LB, with StaticFilesMiddleware and trusted_hosts configured, reload_strategy.exception and file_monitor enabled in staging only.
3. Consolidate scheduled work — move cron entries to the scheduler (CronExpression::isValidExpression() validation is a genuine improvement over upstream's heuristic), and supervisord-managed daemons to SupervisorWorker.
4. Package — workerman:build:phar / workerman:build:bin with runtime_dir and WORKERMAN_RUNTIME_DIR for air-gapped or on-prem targets, verifying 0700 directory creation and writable cache/log paths.
5. Decommission fpm pool, nginx vhost, crontab, and supervisord program only after the service has held steady-state for a defined bake period.

Compatibility. Pin an exact version; keep composer audit in CI (note the repo itself skips audit locally via LINT_SKIP_AUDIT=1 — do not replicate that). Confirm no reliance on PSR-7 middleware (removed in this fork) and no reliance on the deprecated serve_files/root_dir path. Windows and shared-hosting targets are out. Validate that every https:///wss:// listener has non-symlinked cert paths.

Sequencing. (a) Decide track: Symfony-adopt vs Laravel-reference. (b) If adopt, secure internal ownership of the fork or a hard pin with a documented upgrade cadence. (c) Pilot behind feature flag / LB weight 5%. (d) Canary ramp with latency and memory-reload counters as promotion gates. (e) Only then expand to scheduler/supervisor consolidation, which carries the largest blast radius because a supervisor bug takes down background processing rather than one HTTP worker.

Exit criteria for the pilot: no silent worker states, no unreset stateful services after a 24h soak, memory-reload rate below an agreed threshold, and p95 no worse than baseline.

Operational Impact

Maintenance. Ownership is the dominant cost. Expect: upstream merge triage against luzrain/workerman-bundle, tracking walkor/workerman releases, PHP minor upgrades (the CI matrix already covers 8.2–8.5), Symfony 8 alignment, and internal maintenance of the Laravel adapter if that route is taken. The repo's discipline (UPGRADE.md for breaking changes, changelog gate via bin/check-changelog.php, exception-usage lint) lowers this materially — but it lowers our review cost only if we keep the same gates.

Support. No vendor, no SLA, no dependents to lean on. Support model is self-support: internal runbooks, a named owner, and a fork-or-fall-back decision recorded up front. Fallback must be real — the fpm/nginx config should be kept in version control until the bake period ends.

Scaling. processes defaults to CPU×2 per server; reuse_port enables multiple binds for rollout. Horizontal scale stays LB-driven. Watch the memory reload strategy: default limit 128 MB, gc_limit 96 MB, gc_cooldown 60s. Under leaky workloads this produces worker churn — acceptable as a safety valve, unacceptable as steady state. keepalive_timeout 30s and connection_timeout 120s shape connection-pool behavior at the LB and should be tuned per service, not left at defaults. max_package_size 10 MB global with per-server body_size_cap overrides.

Failure modes to instrument and runbook:

• Worker started with no listen → silent zero traffic.
• static_files.allowed_extensions silently ignored under the recommended middleware setup → unintended file exposure.
• Cert/key symlink rejection → TLS listener fails to start (especially K8s secret mounts).
• Stateful service not reset between requests → cross-request data bleed; hardest to detect, worst to explain.
• Blocking I/O in the request path → whole-worker stall, latency cliff under concurrency.
• Memory reload mid-traffic → in-flight request loss unless drain/graceful reload is verified; stop_timeout default 2s is tight.
• Zombie/orphan processes — /proc-based detection and parent-PID tracking exist, but this is now our problem, not systemd's.
• workerman:server status depends on SIGIOT plus a status file with status_timeout 5s → health-check design must not assume it is fast or reliable.
• Cache warmup forks with a 30s timeout (WORKERMAN_CACHE_WARMUP_TIMEOUT) and signal-based success detection — treat warmup failure as a deploy gate, not a warning.
• Fixed test ports 8888/9999/9991 make parallel CI on one host unsafe; plan test isolation accordingly.

Ramp-up. The team needs a new mental model: event loop instead of process-per-request, signal handling, /proc process inspection, Workerman APIs, PHAR builds, and a rewritten on-call runbook (no nginx access log, no fpm pool status page). Estimate 2–4 weeks for a small platform team to reach competence and produce runbooks; add chaos drills for memory reload, orphan cleanup, and scheduler child-failure reaping before production. The absence of php-fpm's per-request isolation is the conceptual jump most engineers underestimate — the reload strategy is a mitigation, not a substitute.

Recommendation. Do not adopt on the strength of 2 stars and 0 dependents. Adopt only where there is a Symfony service, a named internal owner for the fork, a measured win over fpm+nginx, and LB-terminated TLS. Elsewhere, harvest the architecture — middleware pipeline, strategy-based response conversion, memory-reload watchdog, signal-based process supervision, PHAR packaging — and map each to the Octane/RoadRunner equivalent. Re-score once there is a production reference or a maintained upstream.