Notification Sender

Purpose and Scope

The NotificationSender class is responsible for orchestrating the notification delivery process. It serves as the execution engine that coordinates notification dispatch, manages localization, enforces filtering rules, and dispatches lifecycle events. This component bridges the gap between the ChannelManager (see Channel Manager) and the actual channel implementations.

For information about queue-based asynchronous processing, see Queue Integration. For details about specific channel implementations, see Notification Channels.

Sources: src/NotificationSender.php1-199

---

Core Responsibilities

The NotificationSender performs seven primary functions:

Responsibility	Description	Key Methods
Dispatch Orchestration	Routes notifications to appropriate channels for each notifiable entity	send(), sendNow()
Queue Decision	Determines whether to send immediately or queue for async processing	send(), queueNotification()
Localization Management	Resolves and applies locale preferences during notification rendering	preferredLocale(), withLocale()
Event Dispatching	Fires lifecycle events before and after notification delivery	sendToNotifiable(), shouldSendNotification()
Filtering	Evaluates whether a notification should be sent based on rules and events	shouldSendNotification()
ID Management	Assigns unique identifiers to notification instances	sendToNotifiable(), queueNotification()
Input Normalization	Standardizes notifiable entities into collections for batch processing	formatNotifiables()

Sources: src/NotificationSender.php22-199

---

Send Flow Architecture

Send Method Entry Point

The send() method is the primary entry point for notification dispatch. It determines whether to send immediately or queue based on the notification's interface implementation:

Sources: src/NotificationSender.php40-50

Immediate Send Process

The sendNow() method handles synchronous notification delivery. It processes each notifiable entity and sends through all specified channels:

Key Implementation Details:

• Notification Cloning: The original notification is cloned src/NotificationSender.php59 to prevent state pollution across notifiables. Each channel send receives another clone src/NotificationSender.php71
• Unique ID Assignment: A UUID is generated for each notifiable src/NotificationSender.php67 and shared across all channels for that notifiable.
• Anonymous Notifiable Restriction: Database channel is explicitly blocked for AnonymousNotifiable instances src/NotificationSender.php70 since they don't have persistent storage.
• Locale Scoping: All channel sends for a notifiable execute within a locale context src/NotificationSender.php66

Sources: src/NotificationSender.php55-76 src/NotificationSender.php93-108

---

Localization Support

The NotificationSender uses the Localizable trait src/NotificationSender.php24 to manage locale-aware notification rendering. Locale resolution follows a priority chain:

Locale Resolution Implementation

The preferredLocale() method implements this priority chain:

1. Notification-level locale: Highest priority, allows per-notification override
2. Sender-level locale: Set via constructor parameter src/NotificationSender.php33
3. Notifiable preference: Retrieved via HasLocalePreference interface src/NotificationSender.php84-86
4. Default: Falls back to system default if none specified

The resolved locale is applied using withLocale() src/NotificationSender.php66 which ensures all message rendering and channel operations execute in the correct locale context.

Sources: src/NotificationSender.php81-88 src/NotificationSender.php66

---

Event Lifecycle

The NotificationSender dispatches two events during the notification lifecycle:

NotificationSending Event

Fired before delivery, this event allows external listeners to veto the send operation:

The filtering mechanism uses a two-stage approach:

1. Notification Method: If the notification implements a shouldSend() method src/NotificationSender.php115-119 it's called first. Returning false immediately vetoes the send.
2. Event Listeners: The NotificationSending event is dispatched src/NotificationSender.php121-123 Listeners can modify the event's shouldSend() return value to block delivery.

Sources: src/NotificationSender.php113-124

NotificationSent Event

Dispatched after successful delivery src/NotificationSender.php105-107 this event contains:

• The notifiable entity
• The notification instance
• The channel name
• The response from the channel (if any)

This event enables logging, analytics, and audit trail implementations without coupling to the sender.

Sources: src/NotificationSender.php105-107

---

Queue Integration

When a notification implements the ShouldQueue interface src/NotificationSender.php44 the sender creates SendQueuedNotifications jobs instead of sending immediately.

Queue Job Configuration

The queueNotification() method extracts configuration from multiple notification methods:

Configuration Methods

The following notification methods customize queue behavior:

Method	Purpose	Scope
connection	Default queue connection	All channels
viaConnections()	Per-channel connection mapping	Specific channels
queue	Default queue name	All channels
viaQueues()	Per-channel queue mapping	Specific channels
delay	Default delay time	All channels
withDelay($notifiable, $channel)	Dynamic per-channel delay	Specific channels
middleware	Default middleware stack	All channels
middleware($notifiable, $channel)	Dynamic per-channel middleware	Specific channels

Job Creation:

Each channel gets its own SendQueuedNotifications job src/NotificationSender.php177-182 allowing:

• Independent retry policies per channel
• Different queue priorities per channel
• Isolated failure handling

Locale Preservation:

If the sender has a locale set src/NotificationSender.php145-147 it's assigned to the notification before queueing, ensuring the queued job uses the correct locale context.

Sources: src/NotificationSender.php129-185

---

Filtering Mechanism

The shouldSendNotification() method src/NotificationSender.php113-124 provides a multi-layered filtering system:

Filter Layers

Layer 1: Notification Method

If the notification class implements a shouldSend($notifiable, $channel) method src/NotificationSender.php115 it's invoked first. This allows notification-specific filtering logic, such as:

• Business rule validation
• Recipient permission checks
• Rate limiting per notification type

Returning false immediately blocks the send without firing events src/NotificationSender.php116-118

Layer 2: Event System

The NotificationSending event is created and dispatched src/NotificationSender.php121-123 Event listeners can:

• Inspect the notifiable, notification, and channel
• Modify the event to block sending
• Implement cross-cutting concerns (logging, auditing)

The event's shouldSend() method determines final disposition src/NotificationSender.php123

Sources: src/NotificationSender.php113-124

---

Implementation Details

Input Normalization

The formatNotifiables() method src/NotificationSender.php190-198 standardizes input into iterable collections:

This allows the sender to accept:

• Single model instances
• Collections of models (Hyperf\Database\Model\Collection)
• Generic collections (Hyperf\Collection\Collection)
• Plain arrays
• Single non-model objects (e.g., AnonymousNotifiable)

Sources: src/NotificationSender.php190-198

Dependency Injection

The constructor src/NotificationSender.php29-35 receives four dependencies:

Dependency	Type	Purpose
$manager	ChannelManager	Resolves channel drivers for sending
$bus	BusDispatcherContract	Dispatches queue jobs for async notifications
$events	EventDispatcherInterface	Fires lifecycle events
$locale	?string	Optional default locale for all notifications

Sources: src/NotificationSender.php29-35

UUID Generation

Each notifiable receives a unique notification ID via Str::uuid()->toString() src/NotificationSender.php67 src/NotificationSender.php136 This ID:

• Is shared across all channels for a single notifiable
• Enables tracking of multi-channel notifications
• Is assigned to $notification->id src/NotificationSender.php96 src/NotificationSender.php141

For queued notifications, the UUID is generated before job creation src/NotificationSender.php136 to ensure consistency across async operations.

Sources: src/NotificationSender.php67 src/NotificationSender.php96 src/NotificationSender.php136 src/NotificationSender.php141