Laravel Laravel Package

Product Decisions This Supports

• Async work observability roadmap. Queued event listeners are the least-instrumented part of most Laravel apps; this package makes dispatch, execution, retries, and failures traceable per listener class, which is the prerequisite for any credible SLO on background work. Supports decisions like "can we promise order-confirmation emails within 60s?" or "do we need a queue depth dashboard this quarter?"
• Build vs. buy for queue monitoring. The alternative is wiring Queue::before/Queue::failing hooks plus custom log correlation yourself. This package's run-UUID model, retry tracking, and deadline/missing_run expectations are the parts teams consistently underbuild. Adopt when the in-house version would be a side project, not a sprint.
• Incident response and on-call design. missing_run and queue-start/runtime deadlines convert "the worker silently died" into an alert. Directly informs whether you staff on-call for async pipelines or accept best-effort.
• Feature-level reliability triage. With v1.4.0's precise listener allowlisting, you can scope monitoring to the listeners that matter (payments, provisioning, notifications) instead of monitoring everything and drowning in noise. That's a product prioritization lever: instrument the listeners tied to revenue or contractual SLAs first.
• Workload classification. expect_recurring_runs: false (new in v1.4.0) is a deliberate product statement: "this listener fires on irregular events, so silence is not a failure." Lets you onboard event-driven listeners without false-positive pages, which broadens where the package is viable.
• Migration sequencing. Existing queued jobs are not backfilled, so adoption is forward-only — this constrains rollout planning (deploy during a low-traffic window, accept a blind spot for in-flight jobs) rather than blocking it.
• Not a fit for financial audit trails. Fail-open transport with no durable replay means it is an observability tool, not a ledger. Any roadmap item requiring provable delivery records (reconciliation, chargeback evidence, compliance reporting) needs a separate durable system of record.

When to Consider This Package

Consider it when:

• You run queued Laravel event listeners in production and cannot answer "did this listener run, retry, or fail?" without grepping logs.
• You need per-listener alerting rather than job-level or queue-level metrics — i.e., you care that this listener is late, not that the queue has 900 jobs in it.
• You want retry and failure reporting correlated by run UUID across dispatch → execution → retry without building correlation IDs yourself.
• You have a mix of scheduled and event-triggered listeners and need missing_run expectations to apply selectively (the v1.4.0 expect_recurring_runs: false flag).
• You are on Laravel 12 / PHP 8.2+ and want a dependency-light addition rather than a hosted APM commitment.

Look elsewhere when:

• You need durable, replayable delivery guarantees or an audit-grade execution record. Transport is explicitly fail-open with no durable replay.
• You need historical backfill of already-queued work — this release does not backfill.
• Your listeners are wrapped in shared abstractions and you cannot configure intended listener classes explicitly. v1.4.0's tightening means allowlisting CallQueuedListener broadly no longer works; if you cannot enumerate listener classes, you will get less coverage than the previous behavior implied, and might conclude (incorrectly) that you have blanket monitoring.
• Payment or other regulated workloads are the primary target and you need vendor-verified end-to-end evidence: hosted payment-workload E2E verification has not been performed for this release. Treat that as an unvalidated assumption, not a supported use case.
• You need a vendor SLA or hosted control plane. This is a self-operated package; you own the transport, storage, and alerting.
• You require support for older Laravel/PHP versions outside the tested matrix. Validation covers PHP 8.2 + Laravel 12 and PHP 8.5 + Laravel 13, including lowest-supported-dependency and clean-consumer fixtures — solid coverage, but it defines the edge of the supported envelope.

Upgrade note for existing users (behavior change): v1.4.0 changes allowlisting semantics. If anyone previously relied on allowlisting the shared CallQueuedListener wrapper to opt all listeners in, that no longer implies coverage. Audit your configuration and explicitly enumerate intended listener classes before upgrading, or you will silently lose monitoring you believed you had. This is the single highest-risk item in the release and deserves a checklist item, not a changelog skim.

How to Pitch It (Stakeholders)

For executives (one paragraph): We have no reliable way to see whether background work — order confirmations, provisioning, notifications — actually ran. This package adds per-listener tracking for dispatch, retries, and failures, plus alerting when expected runs don't happen, on top of the Laravel queue we already run. It is a low-cost, self-hosted addition rather than a new vendor contract. The honest caveats: it is fail-open by design, it does not retain a replayable history, and it does not retroactively cover jobs already in flight when we turn it on. It makes us observable; it does not make us guaranteed. If we need provable delivery for financial flows, that remains a separate investment.

For engineering leadership: Test coverage is strong — 140 tests / 601 assertions across the full CI matrix, including lowest-supported dependencies and clean consumer fixtures, with database-queue tests covering web dispatch without a worker, precise listener allowlisting, and delayed-then-executed runs reusing the same run UUID. That last case is the one that usually breaks homemade correlation schemes. The v1.4.0 upgrade is small in code and meaningful in behavior: explicit listener configuration replaces the shared-wrapper shortcut, so it is a config audit, not a find-and-replace. Scope the rollout to the two or three listeners attached to revenue or contractual SLAs first; that is where missing_run and runtime deadlines pay for themselves.

For the team doing the work: Plan for one configuration pass (enumerate intended listener classes), one decision pass per listener (expect_recurring_runs true or false), and a deployment window where forward-only instrumentation is acceptable. Do not position this as the answer to "did the payment go through?" — position it as "we would have known within minutes if it hadn't."