Download the PHP package monkeyscloud/monkeyslegion-notifications without Composer

MonkeysLegion Notifications

A multi-channel notification system for the MonkeysLegion framework. Deeply integrated with the MonkeysLegion Queue, Query, and Mail packages while maintaining strict modular isolation.

🚀 Overview

MonkeysLegion Notifications allows you to send messages across various delivery channels (like Mail and Database) following a clean, expressive API. It supports asynchronous delivery out-of-the-box by leveraging the MonkeysLegion-Queue system.

✨ Features

• 📨 Multi-Channel Delivery - Send notifications via Mail, Database, and more.
• ⚡ Queue Integration - Automatically background heavy notification dispatches (e.g., SMTP) using the ShouldQueue interface.
• 🎯 Notifiable Entities - Easy integration with your Models/Entities via the Notifiable trait.
• 🏷️ Attribute Triggers - Trigger notifications automatically using PHP 8 attributes on DTOs or Entity properties.
• 🛡️ PSR Compliant - Built with PSR-14 event dispatching and standard isolation principles.

📦 Installation

⚙️ Setup

You can bootstrap notifications in two ways depending on how much automation you want.

1. Manual setup (full control)

Configure and wire all components yourself.

Use this approach when you want explicit, per-service control over construction and registration.

2. Near-auto setup (ServiceProvider + MonkeysLegion-DI)

Use the package NotificationServiceProvider with the container from monkeyscloud/monkeyslegion-di. The provider wires NotificationManager, channels, AttributeProcessor, and NotificationListener for you.

This package also exposes provider discovery metadata in composer.json:

So if your bootstrap supports MonkeysLegion provider discovery, this provider can be auto-registered. This is the same convention used by MonkeysLegion packages that expose service providers.

📖 Basic Usage

1. Define a Notification

2. Prepare your Notifiable Model

3. Send the Notification

4. Attribute Triggers (Advanced)

You can automatically trigger notifications by using the #[Notify] attribute on your entities or their properties.

The AttributeProcessor scans for these triggers during event lifespan. For more detailed examples and advanced usage (including private getters and global listener mapping), check the Notification Listener Usage Guide.

🔌 Custom Channels (Open Channels)

MonkeysLegion Notifications is an open channels package. This means you can easily extend it by adding your own delivery channels (e.g., Slack, SMS, Push).

To register a custom channel, use the extend method on the NotificationManager:

The callable must return an instance that implements the MonkeysLegion\Notifications\Channels\ChannelInterface.

📦 Project Structure

📡 Scope & Integration

This package is designed as a Producer. It formats messages and submits them to the respective underlying systems:

• Queue: If a notification implements ShouldQueue, it is wrapped in a SendNotificationJob and handed to MonkeysLegion-Queue.

  • [!NOTE] Implement the ShouldSync interface to force immediate execution. For full details on the queue system, visit the MonkeysLegion Queue Documentation.

• Database: Records are persisted using MonkeysLegion-Query.
• Mail: Content is handed over to MonkeysLegion-Mail.

🚦 TODO

• [ ] Slack & SMS & Push Notifications integration

Made with ❤️ by MonkeysLegion