roman-1983/messenger-worker-registry
A Laravel package that provides a registry for messenger workers, making it easy to register, discover, and manage worker definitions in your application. Ideal for organizing background message consumers and keeping worker configuration consistent.
Architecture fit. Weak-to-conditional. The package is a worker registry for Symfony Messenger, and its value surface is narrow and well-defined: register a consumer on start, heartbeat it while running, deregister or expire it on stop, and expose that inventory so humans and automation can answer "what is actually consuming from this transport right now?" That is a legitimate operational gap in most PHP estates. But Laravel's queue system does not emit Symfony Messenger worker lifecycle events, so in a vanilla Laravel app there is no hook to attach to. Fit becomes real only in three scenarios: (1) a hybrid estate where Symfony services and Laravel services coexist and Symfony Messenger is already a committed piece of infrastructure; (2) standalone messenger:consume workers running alongside a Laravel app; (3) a deliberate decision to adopt Symfony Messenger as the async backbone. Note the discrepancy worth flagging in diligence: the package description advertises "easy Laravel integration via service provider," while the deeper assessments describe a Symfony-centric package. That claim is unverified at 2 stars and 0 dependents, and the credibility gap itself is a signal about documentation quality.
Integration feasibility. Low to moderate. Positives: MIT license, Composer-installable, small enough to audit end-to-end in under an hour, and conceptually simple enough to reimplement if needed. Negatives dominate: no dependents, no ecosystem, no evidence of production usage, and no proof of the Laravel-facing claim. A realistic path requires an adapter layer — bootstrapping Symfony DI or bundle registration inside a Laravel process, subscribing to worker start/idle/stop events, selecting and wiring a registry backend (Redis, Doctrine, or cache pool), and defining TTL and eviction semantics. Each of those is a decision the package may or may not make for us, and none are documented in what we have. Treat this as source material and a reference design, not a dependency to install and forget.
Technical risk. High. Concretely: undocumented PHP and symfony/messenger version constraints on a small package often means pinned old versions; unknown registry backend and therefore unknown consistency and availability characteristics; unknown heartbeat/TTL/cleanup behavior, which is the single most common failure mode for naive registries; no load evidence at hundreds or thousands of workers; and no maintainer signal (release cadence, issue response, security posture) to plan around. The compounding risk is ownership: with 0 dependents and 2 stars, we become the de facto maintainer of anything we ship on top of it. A secondary risk is strategic drift — if this package pulls a Laravel team toward running Symfony Messenger in production to justify the adoption, we have let a utility dictate platform architecture.
Key questions for the spike.
Stack fit. Poor for a vanilla Laravel + Horizon shop; conditional for a hybrid Symfony/Laravel estate. Horizon already covers a meaningful slice of this problem space — worker liveness, per-queue throughput, supervision, and restart coordination — and it is Laravel-native, maintained, and understood by the team. If we are Horizon-based, the honest answer is that this package does not fill a gap we have; it fills a gap Horizon's abstraction hides. If we run Symfony Messenger workers — especially in a separate deployment from the Laravel app — the calculus changes and this becomes a plausible narrow utility. Decide that first. Do not let the package drive the platform choice.
Migration path. Time-boxed spike, non-production, one worker pool. Sequence: install via Composer and read composer.json for version constraints; read src/ end-to-end (budget an hour) to identify the storage backend and eviction logic; stand up a single messenger:consume process; verify registration on start, heartbeat persistence across a few intervals, deregistration on clean stop, and eviction after a hard kill (SIGKILL) — the kill test is the real one, since graceful shutdown is the easy path. Confirm reads and writes agree by inspecting Redis/Doctrine directly rather than trusting the package's own reader. Then wrap everything behind an internal interface (for example WorkerRegistry with activeCount(string $queue): int and stale(string $queue): Collection) so no application code imports Symfony classes directly and the package remains replaceable. If the spike passes, pilot a single non-critical consumer pool before any broader rollout, and keep a Laravel-native fallback in the design.
Compatibility. Validate PHP, symfony/messenger, and Laravel versions explicitly — treat all compatibility claims as unproven given zero dependents. Check whether the package requires Symfony FrameworkBundle/DI or can run standalone, since a hard FrameworkBundle dependency is a meaningful cost inside a Laravel process. Confirm behavior against the exact transports in use (Redis, SQS, database, AMQP) rather than a generic claim. Add CI coverage pinning the specific versions we support, because we will be the ones discovering breakage.
Sequencing. (1) Answer the gating question: is Symfony Messenger in scope? If no, stop and evaluate a Laravel-native registry or Horizon-derived telemetry instead. (2) Inventory the current worker lifecycle and the specific observability gap we are trying to close. (3) Spike the package in isolation against a real transport. (4) Build or fork an adapter behind an internal interface, or conclude that an in-house ~200-line equivalent is cheaper. (5) Add heartbeat, TTL, and failure-mode tests, including backend-outage behavior. (6) Pilot one worker pool. (7) Make the build-vs-buy-vs-fork call with spike data in hand. Critically, this must not be sequenced ahead of a Laravel-native alternative — it is a challenger, not an incumbent.
Maintenance. High relative to likely value. Low stars and zero dependents translate into limited community testing, slow or absent issue response, no CVE history to reason about, and real abandonment risk. Plan to pin a version, vendor or fork the code into our repo if we proceed, and own the adapter and the Symfony/Laravel upgrade compatibility work indefinitely. The maintenance burden is not the package's line count — it is the operational contract around heartbeats, TTLs, and cleanup that we will end up defining and defending ourselves.
Support. Community-only, with essentially no evidence of production usage to lean on when something breaks. We must author the runbooks, the dashboards, and the on-call ownership before this touches production. Ramp-up is moderate-to-high for a Laravel team: it requires Symfony Messenger internals (worker events, transports, middleware, bundle/DI conventions) layered on top of Laravel queue operations — a genuinely niche combination. It is low-effort only for a team already fluent in Symfony Messenger, and that is the exception rather than the rule in a Laravel shop.
Scaling. Unknown and must not be assumed. Worker registries can become hot paths precisely when things are going wrong: a restart storm produces a burst of registrations, deregistrations, and heartbeat writes, and a naive registry either melts or leaves ghosts. Design for idempotent registration, short TTLs relative to heartbeat interval, bounded and scheduled cleanup, and reads that are cheap enough to poll from health checks. Load test at the worker counts we actually expect — do not extrapolate from a single-worker spike. If the registry backend is shared with production cache or session traffic, isolate it.
Failure modes to design against. Stale or ghost workers after crashes and ungraceful pod terminations, causing false capacity and scaling decisions. Missed heartbeats producing spurious "worker down" alerts, or the inverse — a dead registry silently reporting zero workers and nobody noticing. Registry backend outage blocking worker startup (fail-closed) when it should fail open and keep consuming. Race conditions during rolling deploys and blue/green cutovers where old and new workers briefly coexist. Silent swallowing of registration errors. Version breakage after a Symfony or Laravel upgrade. Mitigations: alert on stale registrations rather than trusting liveness blindly, add a health endpoint that reports registry freshness alongside worker counts, make registration best-effort so the queue path never depends on the registry, and keep a kill-test in CI.
Ramp-up and recommendation. Treat this as a timeboxed spike or internal fork candidate, not a default platform dependency. Budget one to two days of evaluation against two comparators: an in-house ~200-line Redis-heartbeat registry, and existing tooling already in the estate (Horizon, APM, Prometheus with Messenger middleware, Sentry cron checks). Adopt only if the Symfony Messenger precondition holds and the spike clearly saves more effort than it costs to own. The realistic downside of proceeding naively is not a failed install — it is quietly acquiring a component we must maintain forever to answer a question our existing tooling may already answer.
How can I help you explore Laravel packages today?