Basic Usage

Purpose and Scope

This page demonstrates standard patterns for sending notifications using notifiable entities. It covers the core workflow: creating notification classes, defining delivery channels, and dispatching notifications through the ChannelManager. For asynchronous delivery, see Queued Notifications. For sending to arbitrary recipients without persistent entities, see Anonymous Notifications.

---

Overview of the Notification Flow

The basic notification flow involves three primary components: a notifiable entity (the recipient), a notification class (the message), and the ChannelManager (the dispatcher).

Basic Flow Diagram

Sources: src/ChannelManager.php54-62 src/NotificationSender.php40-50 src/NotificationSender.php55-76

---

Notifiable Entities

A notifiable entity is any object that can receive notifications. Typically, these are user models or other domain entities that implement notification routing methods.

Key Characteristics

Characteristic	Description
Identity	Must be serializable (for queueing)
Routing	Provides channel-specific routing information (email address, Slack webhook, etc.)
Preferences	Optionally implements HasLocalePreference for localization
Flexibility	Can be a Model, plain object, or collection

Routing Methods

Notifiable entities typically define routing methods that channels use to determine delivery destinations:

Method	Channel	Returns
routeNotificationForMail()	Mail	Email address(es)
routeNotificationForSlack()	Slack	Webhook URL or routing config
routeNotificationForDatabase()	Database	Typically null (uses relationship)
routeNotificationForBroadcast()	Broadcast	Channel names

Sources: src/NotificationSender.php61-64 src/NotificationSender.php81-88

---

Notification Classes

Notification classes encapsulate the message content and define which channels should deliver the notification.

Required Structure

Channel Selection via via() Method

The via() method determines which channels will deliver the notification. It receives the notifiable entity as a parameter, allowing channel selection to be dynamic based on recipient preferences or attributes.

The notification sender calls $notification->via($notifiable) at src/NotificationSender.php62 to retrieve the channel list for each recipient.

Message Construction Methods

Each channel expects a corresponding method on the notification class:

Method	Channel	Returns	See Page
toMail($notifiable)	mail	MailMessage	6.1
toSlack($notifiable)	slack	SlackMessage	6.3
toBroadcast($notifiable)	broadcast	BroadcastMessage	6.2
toDatabase($notifiable)	database	array	N/A

Sources: src/NotificationSender.php62 src/NotificationSender.php69-73

---

Sending Notifications

Primary Entry Point: ChannelManager

The ChannelManager serves as the primary facade for dispatching notifications. Access it through dependency injection or the container.

The send() Method

The primary method for notification dispatch is ChannelManager::send(), defined at src/ChannelManager.php54-62:

This method:

1. Creates a NotificationSender instance
2. Injects dependencies: BusDispatcherContract, EventDispatcherInterface, and locale
3. Delegates to NotificationSender::send()

Synchronous vs Asynchronous Dispatch

The NotificationSender::send() method at src/NotificationSender.php40-50 determines the dispatch strategy:

Condition	Action	Method Called
$notification instanceof ShouldQueue	Dispatch to queue system	queueNotification()
Otherwise	Send immediately	sendNow()

For synchronous notifications (covered here), the flow proceeds directly to sendNow().

Sources: src/ChannelManager.php54-62 src/NotificationSender.php40-50

---

The sendNow() Method Flow

The sendNow() method at src/NotificationSender.php55-76 executes the synchronous delivery logic:

Execution Steps

Key Operations

Line	Operation	Purpose
57	formatNotifiables()	Converts single notifiable or array to Collection
59	clone $notification	Preserves original for multiple recipients
62	$notification->via($notifiable)	Retrieves channel list
66	withLocale()	Sets locale context from preferences
67	Str::uuid()->toString()	Generates unique notification ID
70-72	Database channel check	Skips database for AnonymousNotifiable
71	sendToNotifiable()	Dispatches to specific channel

Sources: src/NotificationSender.php55-76

---

Locale Handling

The notification system supports localization through a preference resolution chain:

Locale Resolution Order

The preferredLocale() method at src/NotificationSender.php81-88 implements this resolution strategy. The chosen locale wraps the sending operation via withLocale() at src/NotificationSender.php66 applying the locale context for the duration of that notifiable's notification delivery.

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

---

Channel Delivery and Gates

The sendToNotifiable() Method

At src/NotificationSender.php93-108 the sendToNotifiable() method handles per-channel delivery:

Gate Checking Logic

The shouldSendNotification() method at src/NotificationSender.php113-124 implements a two-stage gate:

Stage	Check	Return False If
1	$notification->shouldSend($notifiable, $channel)	Method exists and returns false
2	NotificationSending event	Event's shouldSend() returns false

Both checks must pass for delivery to proceed. This allows notification classes to define internal logic and external listeners to implement cross-cutting delivery rules.

Sources: src/NotificationSender.php93-108 src/NotificationSender.php113-124

---

Multiple Recipients

Recipient Format Flexibility

The formatNotifiables() method at src/NotificationSender.php190-198 accepts multiple input formats:

Supported Input Types

Input Type	Conversion	Output
Collection	None	Returned unchanged
array	None	Returned unchanged
Model	Wrapped	ModelCollection([$model])
Other object	Wrapped	[$object]

This flexibility allows both single and bulk notification operations using the same API:

Sources: src/NotificationSender.php190-198 src/NotificationSender.php42 src/NotificationSender.php57

---

Complete Delivery Pipeline

End-to-End Code Entity Mapping

Sources: src/ChannelManager.php54-62 src/NotificationSender.php40-50 src/NotificationSender.php55-76 src/NotificationSender.php93-108 src/NotificationSender.php113-124

---

Summary

Basic notification usage follows this pattern:

1. Create a notification class with a via() method and channel-specific message methods
2. Obtain the ChannelManager from the DI container
3. Call send() with notifiable entity(ies) and notification instance
4. The system automatically:
   • Formats recipients into collections
   • Determines channels via via() method
   • Applies locale preferences
   • Executes gate checks
   • Dispatches to appropriate channel drivers
   • Fires lifecycle events

For queued delivery, see Queued Notifications. For routing and message construction details, see the respective channel pages (Mail Channel, Slack Channels, Broadcast Channel).