Laravel Laravel Package

Getting Started

v1.4.0 makes queued Laravel event listener monitoring listener-specific. Start by auditing the package config and any listener allowlists, then configure the exact listener classes you care about rather than the shared CallQueuedListener wrapper.

Minimal steps:

1. Inspect/publish the package config and find the queued-listener monitoring section.
2. Allowlist intended listener FQCNs explicitly, for example App\Listeners\CapturePayment and App\Listeners\SendReceipt.
3. Decide whether each queue workload is recurring. Leave expect_recurring_runs at its default true for regular cadence; set it to false for irregular/event-driven workloads.
4. Verify locally with a database queue: dispatch from a web request without a worker, start the worker later, and confirm the listener is tracked across dispatch, execution, retries, and failure reporting.

First useful use case: monitor a queued listener that is dispatched after a web request, may be delayed or retried, and must report failures. This release’s database-queue coverage specifically exercises web dispatch without a worker, intentional delay, later execution, and the same run UUID across that lifecycle.

Implementation Patterns

• Allowlist per listener, not per wrapper. Configure each queued listener class you want monitored. Treat Illuminate\Events\CallQueuedListener as Laravel’s transport wrapper, not the monitored unit. If one event has several queued listeners, list each listener separately.
• Model the full listener lifecycle. Use the package to observe dispatch, execution, retries, and failure reporting for a specific listener. This is most useful for listeners with side effects such as payment capture, notifications, or external API calls.
• Use expect_recurring_runs=false for irregular workloads. For webhook-triggered, user-triggered, or bursty queue workloads, disable periodic missing_run expectations while retaining queue-start and runtime deadline checks. Do not disable recurring expectations for genuinely scheduled work unless the schedule is intentionally irregular.
• Pair delayed and retried jobs with run-UUID checks. The release notes confirm database-queue tests cover intentional delay and later execution using the same run UUID. In your own tests, assert that dispatch, delayed execution, retry, and failure reporting stay attached to the same listener run.
• Deploy config before dispatching new work. Since existing queued jobs are not backfilled, roll out listener allowlists and expectation settings before relying on monitoring for new production jobs. A queue restart is usually needed after config changes; clear cached config first.
• Use it as observability, not as a durable audit log. The transport remains fail-open without durable replay. Keep application logs, failed-job records, and business-level audit trails for payment or other critical workflows.

Gotchas and Tips

• Behavior change: CallQueuedListener no longer opts in every listener. If an older setup allowlisted the shared wrapper, upgrade auditing is required. Add explicit listener classes or some queued listeners will no longer be monitored.
• Exact class matching matters. Confirm the FQCN that is actually dispatched and executed. Wrappers, aliases, proxied listener names, or unexpected subclasses can make a listener appear unmonitored.
• expect_recurring_runs=false is not a global mute. It disables periodic missing_run expectations only; queue-start and runtime deadlines still apply. Use it deliberately for irregular workloads.
• No backfill for in-flight jobs. Jobs already queued before the change will not be retroactively monitored. Expect a gap during deployment unless you drain or accept the transition period.
• Fail-open transport means missing telemetry is possible. Monitoring should not break queue processing, but it also cannot replay lost signals. Alert on business outcomes and queue failures independently.
• Clear config and restart workers after changes. Run the usual Laravel config-cache clear/rebuild and restart queue workers so listener allowlists and expectation settings take effect.
• Compatibility signals look good, but verify your matrix. The release reports 140 tests / 601 assertions across PHP 8.2 + Laravel 12 and PHP 8.5 + Laravel 13, including lowest supported dependencies and clean consumer fixtures. Still validate your exact PHP/Laravel/queue-driver combination.
• Hosted payment-workload e2e was not performed for this release. If you use this for payment-adjacent listeners, stage-test the exact dispatch, delay, retry, failure, and reporting path before relying on it in production.