Queued Notifications

This document details how to configure notifications for asynchronous processing through the queue system. It covers implementing the ShouldQueue interface, configuring queue behavior (connection, retries, delays), and handling job failures. For information on synchronous notification sending, see Basic Usage. For details on the queue integration architecture, see Queue Integration.

Overview

The notification system automatically detects when a notification should be queued by checking if it implements ShouldQueue. When detected, instead of sending immediately, the system creates a SendQueuedNotifications job that encapsulates the notification and dispatches it to the configured queue system for asynchronous processing.

Sources: src/NotificationSender.php40-50

Making Notifications Queueable

To queue a notification, implement the ShouldQueue interface on your notification class:

The NotificationSender checks this interface at src/NotificationSender.php44 and automatically routes to the queueing path when present. No additional configuration is required for basic queueing behavior.

Sources: src/NotificationSender.php44-47

Queue Configuration Properties

The SendQueuedNotifications job extracts configuration directly from properties on the notification instance. These properties control queue behavior, retry logic, and job execution.

Basic Configuration Properties

Property	Type	Purpose	Extracted At
connection	?string	Queue connection name	src/NotificationSender.php149
queue	?string	Queue name	src/NotificationSender.php155
delay	mixed	Delay before processing (seconds or array)	src/NotificationSender.php161
tries	?int	Maximum number of attempts	src/SendQueuedNotifications.php68
timeout	?int	Job timeout in seconds	src/SendQueuedNotifications.php69
maxExceptions	?int	Maximum unhandled exceptions before failing	src/SendQueuedNotifications.php70
middleware	array	Queue middleware pipeline	src/NotificationSender.php167-174
afterCommit	?bool	Wait for database transaction commit	src/SendQueuedNotifications.php72-76

Example notification with configuration:

Sources: src/NotificationSender.php149-182 src/SendQueuedNotifications.php68-78

Per-Channel Configuration

The system supports different queue configurations for different channels through optional methods on the notification class. This allows, for example, email notifications to use one queue connection while Slack notifications use another.

viaConnections()

Returns an array mapping channel names to connection names:

The system checks for this method at src/NotificationSender.php151-153 and uses the channel-specific connection if available, otherwise falls back to the connection property.

viaQueues()

Returns an array mapping channel names to queue names:

The system checks for this method at src/NotificationSender.php157-159 and uses the channel-specific queue if available, otherwise falls back to the queue property.

withDelay()

Returns the delay for a specific notifiable and channel:

The system calls this method at src/NotificationSender.php163-165 if present. The delay property can also be an array mapping channels to delays: ['mail' => 60, 'slack' => 30]. The job dispatcher handles array delays by extracting the channel-specific value at src/NotificationSender.php180

middleware()

Returns middleware for a specific notifiable and channel:

The system calls this method at src/NotificationSender.php169-174 and merges the result with the middleware property array.

Sources: src/NotificationSender.php151-174

The SendQueuedNotifications Job

The SendQueuedNotifications class is the queue job that encapsulates notification delivery. It implements ShouldQueue and uses several queue-related traits.

Constructor

The constructor at src/SendQueuedNotifications.php63-79 performs the following:

1. Wraps notifiables in a Collection via wrapNotifiables() src/SendQueuedNotifications.php84-94
2. Stores the notification and channels
3. Extracts tries, timeout, maxExceptions from notification properties
4. Determines afterCommit behavior by checking ShouldQueueAfterCommit interface or property
5. Sets shouldBeEncrypted if notification implements ShouldBeEncrypted

handle() Method

When the queue worker processes the job, it calls handle() at src/SendQueuedNotifications.php99-102 which receives the ChannelManager via dependency injection and delegates to sendNow():

This ensures the notification is sent synchronously in the worker context, bypassing the queue check.

Sources: src/SendQueuedNotifications.php63-102

Encryption

Notifications can be encrypted in the queue by implementing the ShouldBeEncrypted interface:

The SendQueuedNotifications constructor checks for this interface at src/SendQueuedNotifications.php78 and sets the shouldBeEncrypted property accordingly. The queue system will then encrypt the serialized job payload before storing it.

Sources: src/SendQueuedNotifications.php78

Retry Logic

The retry behavior is controlled by methods and properties on the notification class. The SendQueuedNotifications job proxies these to the queue system.

backoff()

The backoff() method at src/SendQueuedNotifications.php125-132 returns the number of seconds to wait before retrying. It checks for either a backoff property or method on the notification:

retryUntil()

The retryUntil() method at src/SendQueuedNotifications.php137-144 returns a DateTime representing the absolute deadline for retries. After this time, the job will not be retried even if attempts remain:

Both methods return null if neither a property nor method is defined on the notification.

Sources: src/SendQueuedNotifications.php125-144

Failure Handling

When a queued notification permanently fails (exhausts retries or exceeds retryUntil), the SendQueuedNotifications job's failed() method is called at src/SendQueuedNotifications.php115-120 This method checks if the notification implements a failed() method and calls it with the exception:

Example notification with failure handling:

Sources: src/SendQueuedNotifications.php115-120

Job Display Name

The displayName() method at src/SendQueuedNotifications.php107-110 returns the notification class name for display in queue monitoring tools:

This makes it easier to identify notification jobs in queue dashboards and logs.

Sources: src/SendQueuedNotifications.php107-110

Configuration Extraction Flow

The following diagram shows how configuration is extracted from the notification and applied to the job:

Sources: src/NotificationSender.php129-185 src/SendQueuedNotifications.php63-79

Complete Lifecycle

The complete lifecycle of a queued notification from dispatch to completion:

Sources: src/NotificationSender.php40-50 src/NotificationSender.php129-185 src/SendQueuedNotifications.php63-79 src/SendQueuedNotifications.php99-102 src/SendQueuedNotifications.php115-144