PHPackages                             monkeyscloud/monkeyslegion-notifications - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Mail & Notifications](/categories/mail)
4. /
5. monkeyscloud/monkeyslegion-notifications

ActiveLibrary[Mail & Notifications](/categories/mail)

monkeyscloud/monkeyslegion-notifications
========================================

1.0.0(2mo ago)10MITPHP

Since Apr 10Pushed 2mo agoCompare

[ Source](https://github.com/MonkeysCloud/MonkeysLegion-Notifications)[ Packagist](https://packagist.org/packages/monkeyscloud/monkeyslegion-notifications)[ RSS](/packages/monkeyscloud-monkeyslegion-notifications/feed)WikiDiscussions main Synced 3w ago

READMEChangelogDependencies (13)Versions (2)Used By (0)

MonkeysLegion Notifications
===========================

[](#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
----------

[](#-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
----------

[](#-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
--------------

[](#-installation)

```
composer require monkeyscloud/monkeyslegion-notifications
```

⚙️ Setup
--------

[](#️-setup)

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

### 1. Manual setup (full control)

[](#1-manual-setup-full-control)

Configure and wire all components yourself.

```
use MonkeysLegion\Events\ListenerProvider;
use MonkeysLegion\Notifications\Attributes\AttributeProcessor;
use MonkeysLegion\Notifications\Channels\DatabaseChannel;
use MonkeysLegion\Notifications\Channels\MailChannel;
use MonkeysLegion\Notifications\NotificationListener;
use MonkeysLegion\Notifications\NotificationManager;

$manager = new NotificationManager(
    events: $eventDispatcher, // optional
    queue: $queueDispatcher   // optional
);

$manager->extend('mail', fn () => new MailChannel($mailer, $renderer));
$manager->extend('database', fn () => new DatabaseChannel($queryBuilder, 'notifications'));

$processor = new AttributeProcessor($manager);
$listenerProvider = new ListenerProvider();
$listener = new NotificationListener(
    manager: $manager,
    processor: $processor,
    dispatcher: $listenerProvider
);
```

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

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

[](#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`:

```
"extra": {
  "monkeyslegion": {
    "providers": [
      "MonkeysLegion\\Notifications\\Providers\\NotificationServiceProvider"
    ]
  }
}
```

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
-------------

[](#-basic-usage)

### 1. Define a Notification

[](#1-define-a-notification)

```
namespace App\Notifications;

use MonkeysLegion\Notifications\Contracts\NotificationInterface;
use MonkeysLegion\Notifications\Messages\MailMessage;
use MonkeysLegion\Queue\Contracts\ShouldQueue; // Optional: for background sending

class InvoicePaid implements NotificationInterface, ShouldQueue
{
    public function __construct(public float $amount) {}

    public function via($notifiable): array
    {
        return ['mail', 'database'];
    }

    public function toMail($notifiable): MailMessage
    {
        return (new MailMessage)
            ->subject('Invoice Paid')
            ->line("You have paid an invoice of ${$this->amount}")
            ->action('View Invoice', 'https://example.com/invoice/1');
    }

    public function toDatabase($notifiable): array
    {
        return [
            'amount' => $this->amount,
            'message' => "Invoice of ${$this->amount} paid."
        ];
    }
}
```

### 2. Prepare your Notifiable Model

[](#2-prepare-your-notifiable-model)

```
use MonkeysLegion\Notifications\Traits\Notifiable;

class User
{
    use Notifiable;

    public string $email = 'user@example.com';
}
```

### 3. Send the Notification

[](#3-send-the-notification)

```
$user->notify(new InvoicePaid(99.99));
```

### 4. Attribute Triggers (Advanced)

[](#4-attribute-triggers-advanced)

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

```
use MonkeysLegion\Notifications\Attributes\Notify;
use App\Notifications\LowBalanceWarning;

class Account
{
    use Notifiable;

    #[Notify(LowBalanceWarning::class)]
    public float $balance = 10.00;
}
```

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](notification_listener_usage.md).

🔌 Custom Channels (Open Channels)
---------------------------------

[](#-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`:

```
$notificationManager->extend('my-channel', function () {
    return new MyCustomChannel(/* dependencies */);
});
```

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

📦 Project Structure
-------------------

[](#-project-structure)

```
monkeyslegion-notifications/
├── src/
│   ├── Attributes/
│   │   ├── Notify.php              # Attribute-driven triggers
│   │   └── AttributeProcessor.php  # Logic to scan and trigger
│   ├── Channels/
│   │   ├── ChannelInterface.php    # Blueprint for all drivers
│   │   ├── DatabaseChannel.php     # Logic for saving to DB
│   │   └── MailChannel.php         # Logic for sending emails
│   ├── Contracts/
│   │   ├── NotifiableInterface.php # For entities that receive notifications
│   │   └── NotificationInterface.php # For the notification classes themselves
│   ├── Events/
│   │   ├── NotificationSent.php    # PSR-14 event
│   │   └── NotificationFailed.php  # PSR-14 event
│   ├── Exceptions/
│   │   └── CouldNotSendNotification.php
│   ├── Jobs/
│   │   └── SendNotificationJob.php  # Queue wrapper
│   ├── Messages/
│   │   ├── MailMessage.php         # Fluent builder for mail content
│   │   └── DatabaseMessage.php     # Formatter for DB arrays
│   ├── Traits/
│   │   └── Notifiable.php          # The "Glue" for your User/Entity models
│   └── NotificationManager.php     # The "Dispatcher" (Entry point)
├── database/
│   └── migrations/                 # Default sql migrations for DB channel
├── config/
│   ├── notifications.mlc           # MonkeysLegion Config format
│   └── notifications.php           # PHP array config using $_ENV

```

📡 Scope & Integration
-------------------------

[](#-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](https://monkeyslegion.com/docs/packages/queue).
- **Database**: Records are persisted using `MonkeysLegion-Query`.
- **Mail**: Content is handed over to `MonkeysLegion-Mail`.

🚦 TODO
------

[](#-todo)

- Slack & SMS & Push Notifications integration

---

Made with ❤️ by MonkeysLegion

###  Health Score

33

—

LowBetter than 72% of packages

Maintenance87

Actively maintained with recent releases

Popularity2

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity34

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

73d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/2913369?v=4)[Jorge Peraza](/maintainers/yorchperaza)[@yorchperaza](https://github.com/yorchperaza)

---

Top Contributors

[![Amanar-Marouane](https://avatars.githubusercontent.com/u/155680356?v=4)](https://github.com/Amanar-Marouane "Amanar-Marouane (3 commits)")

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/monkeyscloud-monkeyslegion-notifications/health.svg)

```
[![Health](https://phpackages.com/badges/monkeyscloud-monkeyslegion-notifications/health.svg)](https://phpackages.com/packages/monkeyscloud-monkeyslegion-notifications)
```

###  Alternatives

[symfony/symfony

The Symfony PHP framework

31.4k86.9M2.2k](/packages/symfony-symfony)[symfony/mailer

Helps sending emails

1.6k394.6M1.3k](/packages/symfony-mailer)[symfony/postmark-mailer

Symfony Postmark Mailer Bridge

4819.3M57](/packages/symfony-postmark-mailer)[phpro/soap-client

A general purpose SoapClient library

8895.9M52](/packages/phpro-soap-client)[web-auth/webauthn-lib

FIDO2/Webauthn Support For PHP

1237.8M120](/packages/web-auth-webauthn-lib)[drupal/core-recommended

Locked core dependencies; require this project INSTEAD OF drupal/core.

6941.5M396](/packages/drupal-core-recommended)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)