Notification System

This document describes the multi-channel notification system that enables sending messages through various delivery methods including email and SMS. The notification system consists of a core package (notification) and channel-specific extensions (notification-mail and notification-easysms). For email-specific implementation details, see 8.2. For SMS configuration and usage patterns, refer to the notification-easysms component documentation.

System Architecture

The notification system follows a driver-based architecture where notifications can be delivered through multiple channels. Each channel has its own package and implements specific delivery mechanisms.

Package Organization

Package	Purpose	Key Classes
friendsofhyperf/notification	Core notification framework	Notification, Notifiable trait
friendsofhyperf/notification-mail	Email delivery channel	MailMessage, mail channel driver
friendsofhyperf/notification-easysms	SMS delivery channel	EasySMS channel driver

Sources: src/.github/profile/README.md36-38 docs/en/components/notification-mail.md1-111

Component Dependencies

Diagram: Notification System Component Flow

Sources: docs/en/components/notification-mail.md11-46

Notifiable Trait

The Notifiable trait is the entry point for adding notification capabilities to any model. When added to a model class, it provides the notify() method for sending notifications.

Integration Pattern

Models that should receive notifications must:

1. Use the Notifiable trait
2. Define routing methods for each notification channel

Sources: docs/en/components/notification-mail.md11-46

Routing Methods

The trait enables channel-specific routing through method naming convention:

Method Pattern	Purpose	Return Type
routeNotificationForMail()	Email address for mail channel	string
routeNotificationForEasySms()	Phone number for SMS channel	PhoneNumber or string
routeNotificationFor{Channel}()	Generic pattern for custom channels	Mixed

The routing methods are called automatically when a notification is sent through the corresponding channel. If a routing method is not defined for a channel specified in the notification's via() method, that channel will be skipped.

Sources: docs/en/components/notification-mail.md39-45

Notification Classes

Notification classes encapsulate the message content and delivery logic for a specific notification type. Each notification defines which channels it should be sent through and how to format the message for each channel.

Notification Lifecycle

Diagram: Notification Delivery Sequence

Sources: docs/en/components/notification-mail.md66-89

Notification Structure

Each notification class must implement:

Method	Required	Purpose	Return Type
via(object $notifiable)	Yes	Specify delivery channels	array<int, string>
toMail(object $notifiable)	If using mail	Format message for email	MailMessage
toEasySms(object $notifiable)	If using SMS	Format message for SMS	Message object
toArray(object $notifiable)	Optional	Array representation	array

The via() method returns an array of channel names. Valid channel names correspond to registered channel drivers. The notification system will call the appropriate to{Channel}() method for each channel specified.

Sources: docs/en/components/notification-mail.md66-102

Mail Channel Implementation

The mail channel enables sending email notifications using the MailMessage builder class for fluent message construction.

MailMessage Builder

The MailMessage class provides a fluent API for constructing email notifications:

Method	Parameters	Purpose
from()	string $address, string $name = null	Set sender address and name
replyTo()	string $address, string $name = null	Set reply-to address
subject()	string $subject	Set email subject line
markdown()	string $view, array $data = []	Use markdown template
view()	string $view, array $data = []	Use blade template
greeting()	string $greeting	Set greeting text
line()	string $line	Add line of text
action()	string $text, string $url	Add call-to-action button
cc()	string|array $address	Add CC recipients
bcc()	string|array $address	Add BCC recipients

Example usage pattern:

Sources: docs/en/components/notification-mail.md86-89

Mail Template Rendering

The mail channel supports two template formats:

1. Markdown Templates: Specified via markdown() method, rendered from .blade.php files in storage/view/
2. Blade Templates: Specified via view() method, standard Hyperf view rendering

Template files are resolved through Hyperf's view system. The markdown method automatically wraps content in an email layout with styling.

Sources: docs/en/components/notification-mail.md107-111

Code Generation

The notification system provides console commands for scaffolding notification classes.

Available Commands

Command	Purpose	Output Location
gen:markdown-mail {name}	Generate markdown mail notification	App\Mail\{Name}.php

Example command execution:

This generates a notification class with:

• Constructor for initialization
• via() method returning ['mail']
• toMail() method returning a configured MailMessage
• toArray() method for array representation

Sources: docs/en/components/notification-mail.md50-104

Channel Registration and Routing

Channel Resolution

Diagram: Channel Resolution and Message Routing

Sources: docs/en/components/notification-mail.md39-89

Channel Method Mapping

The notification system uses a naming convention to map channel names to methods:

1. Channel name from via(): 'mail'
2. Routing method: routeNotificationForMail() (camelCase with 'For')
3. Message builder method: toMail() (camelCase with 'to')

This convention allows adding custom channels by:

• Implementing a channel driver
• Defining routeNotificationFor{Channel}() on notifiable models
• Implementing to{Channel}() on notification classes

Integration with Mail Component

The notification-mail package depends on the friendsofhyperf/mail component for actual email delivery. The mail channel driver:

1. Receives formatted MailMessage objects from notification classes
2. Converts them to Mailable instances
3. Passes them to the MailManager for sending via configured mailers

This separation allows notifications to use the same mail infrastructure (SMTP configuration, queuing, etc.) as direct mail sending. For mail transport configuration, queue settings, and markdown template customization, see 8.2.

Sources: docs/en/components/notification-mail.md1-7

Usage Patterns

Sending Notifications

Queueing Notifications

Notifications can implement ShouldQueue to be sent asynchronously:

Queued notifications are automatically dispatched to the async queue system, leveraging the queue infrastructure described in the monorepo's async job handling (see Diagram 5 in high-level architecture).

Sources: tests/Pest.php29

Testing Notifications

The test suite demonstrates notification usage patterns:

Test cases should verify:

1. Notification routing methods return correct addresses
2. via() method returns expected channels
3. Message builders produce correct output
4. Channel-specific formatting methods work properly

Sources: tests/Pest.php29