System Notifications

Configurable system notification definitions for Laravel Enso applications.

Description

System Notifications stores notification definitions, channel templates, context-defined placeholders, handler-driven recipients, and dispatch logs.

This package does not replace laravel-enso/notifications. The existing notifications package remains responsible for the notification inbox, unread counts, read/delete endpoints, and broadcast channel plumbing. This package owns the definition and dispatch orchestration layer.

Installation

Install the package through Composer:

composer require laravel-enso/system-notifications

Run migrations after installing:

php artisan migrate

Features

• defines system notifications in the database
• supports mail, SMS, inbox, and optional mobile push delivery
• validates {placeholder} usage through context-defined placeholders
• resolves to and cc recipients through notification handlers
• exposes administration endpoints for contexts, placeholders, and notification options
• exposes context registry contracts for consuming packages
• sends SMS through an application-bound SmsSender
• sends mobile notifications through an optional application-bound MobilePushSender
• logs notification dispatch per channel and recipient
• ships Enso routes, form, catalogue table, logs table, permissions, and menu structure

Contexts

Contexts are code-defined and registered by the consuming application or package:

use LaravelEnso\SystemNotifications\Resolvers\Contexts;

Contexts::register(ProjectContext::class);

Context classes implement:

LaravelEnso\SystemNotifications\Contracts\Context

Contracts

• Contracts\Context
• Contracts\Placeholder
• Contracts\Handler
• Contracts\MobilePushNotification
• Contracts\SmsSender
• Contracts\MobilePushSender
• Data\MobilePushMessage
• Data\MobilePushResult
• Exceptions\MobilePushDelivery

Handlers return to() and cc() email address arrays for mail, sms() phone number arrays for SMS, and push() notifiable arrays for push/database notifications.

Applications that enable SMS must bind SmsSender to their own implementation. Saving an SMS-enabled notification fails validation while no sender is registered.

The persisted push flag and its title/body templates represent the notification inbox. When the application binds MobilePushSender and its supports() method accepts a notifiable, the same notification is also delivered through the mobile_push channel. Without that binding, inbox and broadcast behavior stays unchanged.

MobilePushSender::send() receives a MobilePushMessage containing the Laravel notification ID, definition slug, title, body, and optional provider metadata. Application notifications may implement MobilePushNotification to reuse the package mobile channel without becoming catalogue-driven notifications. When definition() returns null, delivery continues and catalogue logging is skipped. The sender returns MobilePushResult::accepted() with optional provider references or MobilePushResult::skipped() with an optional reason. Provider references are stored as JSON in the dispatch log.

Providers should throw MobilePushDelivery::transient() for errors that may be retried and MobilePushDelivery::permanent() for terminal failures. Mobile push uses the notifications queue, dispatches after the surrounding database transaction commits, and is attempted at most four times with 10, 60, and 300 second backoffs. Its job shares the Laravel notification UUID with the inbox and broadcast jobs.

Channel and recipient failures are isolated and logged. A failed recipient does not prevent subsequent recipients or other configured channels from being scheduled.

Notification::dispatch() returns false when the definition is inactive or the handler rejects the context, and true after the enabled channels have been scheduled. Applications can use this result to avoid marking skipped domain events as notified.

Menus

The package exposes a nested administration menu:

• Administration > Notifications
• Administration > Notifications > Catalogue
• Administration > Notifications > Logs

Catalogue manages notification definitions. Logs displays dispatch logs from system_notification_logs and supports filtering by notification, context, channel, status, and creation date. push log entries represent inbox delivery, while mobile_push entries represent the external mobile provider. A mobile Succeeded status means the provider accepted the publish request; it does not guarantee delivery to a device.

Routes

Main route group:

• api/administration/system-notifications

Named route groups:

• administration.systemNotifications.catalogue.*
• administration.systemNotifications.logs.*

Companion Frontend Package

• @enso-ui/system-notifications

License

MIT.