README

A framework-agnostic notification core with a thin Laravel adapter.
It provides a standardized notification data model and orchestrator, following the principles of modularity, RBAC, user preferences, and fan-out delivery described in the Generalized Notification Data Architecture for Scalable E-commerce and Beyond paper.

✨ Features

Framework-agnostic Core (pure PHP, no Laravel dependencies)
Standardized Notification Entity (id, type, source, recipients, channels, content, priority, timestamp, status, tenant)
RBAC Policy support (role → type authorization)
User Preferences filtering per notification type/channel
Template Engine abstraction (Blade adapter included)
Channel abstraction (Email, In-App, extendable to SMS, Push, Slack…)
Queue fan-out (each channel dispatched as a separate job)
Laravel integration via ServiceProvider and auto-discovery

📦 Installation

Require via Composer:

composer require tetthys/notification

⚙️ Laravel Setup

Publish config & migrations:

php artisan vendor:publish --tag=tetthys-notification-config
php artisan vendor:publish --tag=tetthys-notification-migrations
php artisan notifications:table
php artisan migrate

Run the queue worker:

php artisan queue:work

🚀 Usage Example (Laravel)

Trigger a notification when an order is completed:

use App\Events\OrderCompleted;
use Tetthys\Notification\Integration\Laravel\LaravelNotifier;

final class SendOrderCompletedNotification
{
    public function __construct(private LaravelNotifier $notifier) {}

    public function handle(OrderCompleted $event): void
    {
        $order = $event->order;

        $this->notifier->send([
            'callerRole' => 'OrderService',
            'type'       => 'OrderCompleted',
            'recipients' => [(string)$order->user_id],
            'data'       => [
                'subject'  => "Order #{$order->id} completed",
                'title'    => "Order Completed",
                'body'     => "Total: {$order->amount}₩. Thank you for your purchase!",
                'priority' => 1,
                'tenantId' => (string)$order->tenant_id,
            ],
            'defaults'   => ['email','inApp'],
            'source'     => 'OrderService',
        ]);
    }
}

🧪 Testing

The core is fully testable with in-memory doubles. Example (Pest):

it('filters channels by user preferences and enqueues jobs', function () {
    $svc = app(\Tetthys\Notification\Core\NotificationService::class);

    $notification = $svc->trigger(
        callerRole: 'OrderService',
        type: 'OrderCompleted',
        recipients: ['U1'],
        data: ['subject' => 'Your order', 'body' => 'Confirmed'],
        defaultChs: ['email','sms','inApp'],
        source: 'OrderService'
    );

    expect($notification->type)->toBe('OrderCompleted');
});

🛠️ Extending

Add new Channel implementations (e.g., SMS, Push, Slack)
Add custom TemplateEngine implementations
Override Preferences with your own storage (DB, Redis, API)

tetthys / notification

Maintainers

Details