NotificationAPI Module

Module that allows the configuration of notifications based on a set of configurable rules.
For now everything is done in config but this module has been built with a future dashboard UI in mind.

Each notification belongs to a notification type that itself refers to an event listener, that will look for all notification types consuming it during an event handling and send all notifications configured for that type.

Quick start

Adding new notifications can be done by adding a new array to the notifications array config under config('notification_api.notifications').
Simply look at the example under NotificationApi/Config/notification_api config file.
Your can create a notification for an existing type, e.g Workflow Transitions, or create your own.

Notification config structure

Each notification has:

  • A name to describe your notification
  • A notificationType class that is bound to an event listener acting as trigger
  • A notificationClass that defines its template and will be used to instantiate an Illuminate\Notifications\Notification to send.
  • Rules that must be true on the event for the notification to be sent and must match options defined by the notificationType
  • Recipients that can be:
    • a list of users populated by the author, users of certain roles, a list of user ids
    • a list of anonymous emails
  • Delivery channels that can be customised but default to email and/or in-app (database)

Notification types

The existing WorkflowTransitionNotificationType provides a comprehensive example of usage.

Notification types are the link between the notification config and the event that should trigger the notification.
They contain the business logic required to setup a notification such as rules: conditions that should be met by an event for a notification to be sent.
They are also in charge of retrieving values from the event.

Each notification type should:

  • Be placed in your module under Plugins/NotificationTypes
  • Implement the NotificationApi/Contracts/NotificationTypeInterface
  • Extend NotificationApi/Plugins/NotificationTypes/BaseNotificationType
  • Define its own getEvent() and setEvent() methods using appropriate type hints, matching event type.

Each notification type should specify an $eventListener property set to the class of an event listener.

Event listeners

You can add your own event listener making sure it listens to an event.

Each event listener should:

  • Be placed in your module under /Listeners
  • Implement the NotificationApi/Contracts/NotificationListenerInterface
  • Extend NotificationApi/Listeners/BaseNotificationListener
  • Be registered against the event in your module EventServiceProvider, see Registering Events & Listeners

Events

  • Events processed by notification types must implement the NotificationApi/Contracts/NotificationEventInterface.
  • Any event property should be accessed by accessors defined in new interface that the event implements. See for instance WorkflowApi/Contracts/WorkflowNotificationEventInterface.

Notification classes

You can customise the content of a notification instance sent by adding your own Notification class and specifying it in your notification config.
Extending NotificationApi/Notifications/BaseNotification will provide handy helpers as well as NotificationApi/Notifications/WorkflowTransitionNotification.
See for example the class ContentModeratedAuthorNotification.

Queues

Both listeners and individual notifications instances are queued in the database table jobs.
They use the queue name notifications by default but this can be customised.

Web sockets / Broadcasting

This is the ability to send messages to the frontend without a page reload. It is great for things like notifications.

To send a broadcast notification to a user, use the following:

$user->sendSocketsNotification('my:event:name', ['some' => 'data']);

To receive that in JS:

window.DistrictEvent.listen('my:event:name', (data) => {
    data === { some: 'data' };
})

NOTE: To debug the sockets in js, start by set BROADCAST_JS_DEBUGGING=true in your .env file

Websockets server

A websockets server is required to handle the messaging between front and backend. Soketi works well and we have a hosted version at https://ws.stack.host Commercial alternative is Pusher.

See .env file for important vars

PUSHER_HOST=ws.stack.host
PUSHER_APP_ID=add-to-sockets-server
PUSHER_APP_KEY=add-to-sockets-server
PUSHER_APP_SECRET=add-to-sockets-server
PUSHER_PORT=443