Overview

This document introduces the hypervel/notifications package, its purpose, core capabilities, and architectural components. It provides a high-level understanding of how the notification system integrates with the Hypervel framework to deliver multi-channel notifications.

For detailed information about specific components, see:

• Package structure and dependencies: Package Structure and Integration
• Core architectural components: Core Architecture
• Notification sending patterns: Sending Notifications
• Channel implementations: Notification Channels

Purpose

The hypervel/notifications package provides a unified API for sending notifications across multiple delivery channels including email, Slack, real-time broadcasts, and database storage. The package abstracts channel-specific delivery logic, supports asynchronous processing through queue integration, and provides extensibility through PSR-14 event dispatching and custom channel registration.

Sources: composer.json1-59

Key Capabilities

The notification system offers the following core capabilities:

Capability	Description	Key Components
Multi-Channel Delivery	Send notifications through mail, Slack, broadcast, and database channels	ChannelManager, channel implementations
Asynchronous Processing	Queue notifications for background processing with retry logic	SendQueuedNotifications, queue integration
Rich Message Construction	Build structured messages with channel-specific features	MailMessage, SlackMessage, Block Kit components
Anonymous Notifications	Send to arbitrary recipients without persistent entities	AnonymousNotifiable
Locale Management	Apply locale context for notification content	NotificationSender locale handling
Event-Driven Hooks	Observe and control notification lifecycle through events	NotificationSending, NotificationSent events
Object Pooling	Reuse expensive driver instances for performance	NotificationPoolProxy
Custom Channels	Register custom delivery channels through extension API	ChannelManager::extend()

Sources: composer.json1-59

Framework Dependencies

The package builds on the Hyperf 3.1 framework and integrates with several Hypervel ecosystem components:

Core Hyperf Dependencies

Sources: composer.json28-41

System Architecture

The notification system consists of three primary architectural layers:

Core Components

Component	File Path	Responsibility
NotificationServiceProvider	src/NotificationServiceProvider.php	Loads notification views from publish/resources/views directory
ConfigProvider	Referenced in composer.json	Registers package configuration with framework
ChannelManager	Core orchestration	Resolves channels, manages driver lifecycle, contextual configuration
NotificationSender	Core orchestration	Orchestrates delivery across channels, manages locale, dispatches events
SendQueuedNotifications	Queue integration	Processes queued notifications asynchronously with retry logic

Sources: src/NotificationServiceProvider.php1-16 composer.json46-54

Notification Flow

The following sequence demonstrates the basic notification delivery flow:

Synchronous vs Asynchronous Processing

Processing Mode	Trigger	Flow
Synchronous	Notification does not implement ShouldQueue	ChannelManager → NotificationSender::send() → immediate channel delivery
Asynchronous	Notification implements ShouldQueue	ChannelManager → NotificationSender::send() → SendQueuedNotifications job → queue storage → worker → NotificationSender::sendNow() → channel delivery

Sources: Analysis of system architecture diagrams provided

Package Registration

The package registers with the Hyperf/Hypervel framework through two providers:

ConfigProvider

Registered via composer.json extra configuration:

The ConfigProvider registers package configuration and bindings with the dependency injection container.

Sources: composer.json46-49

NotificationServiceProvider

Registered via composer.json Hypervel providers:

The NotificationServiceProvider loads notification view templates from the publish/resources/views directory using the notifications namespace.

Sources: composer.json50-53 src/NotificationServiceProvider.php9-14

Channel Types

The package provides built-in support for multiple delivery channels:

Channel	Purpose	Message Type	External Integration
Mail	Email delivery	MailMessage	hypervel/mail MailFactory
Broadcast	Real-time WebSocket events	BroadcastMessage	hypervel/broadcasting
Database	Persist notifications to database	Generic	hyperf/database ORM
Slack (Web API)	Slack message via chat.postMessage	SlackMessage	Slack Web API
Slack (Webhook)	Slack message via incoming webhook	SlackMessage	Slack Webhook URL

For detailed information about specific channels, see Notification Channels.

Sources: Analysis of system architecture diagrams provided

Extensibility

The system provides multiple extension points:

Custom Channels

Register custom delivery channels using ChannelManager::extend():

See Extending the System for detailed guidance.

Event Listeners

Attach PSR-14 event listeners to observe notification lifecycle:

• NotificationSending: Fired before channel delivery (cancellable)
• NotificationSent: Fired after successful delivery
• BroadcastNotificationCreated: Fired for broadcast channel notifications

Object Pooling

Expensive channel drivers can be wrapped in NotificationPoolProxy for instance reuse, improving performance for high-throughput scenarios.

Sources: Analysis of system architecture diagrams provided

License

The package is released under the MIT License with copyright held by Taylor Otwell and Hypervel.

Sources: LICENSE.md1-23

Next Steps

• Understand package structure and dependencies: Package Structure and Integration
• Learn about core architectural components: Core Architecture
• Start sending notifications: Sending Notifications
• Explore available delivery channels: Notification Channels
• Build custom message types: Message Construction
• Create custom channels: Extending the System