Pony.fm/documentation/notifications.md

Developing notifications for Pony.fm

Pony.fm's notification system is designed to support various notification delivery methods. The types of notification one can receive are defined in the NotificationHandler interface, which is implemented by every class that needs to know about the various notification types.

Sending a notification

The Notification facade is used to send notifications as follows:

use Notification;

// Something happens, like a  new track getting published.
$track = new Track();
...

// The "something" is done happening! Time to send a notification.
Notification::publishedNewTrack($track);

This facade has a method for every notification type, drawn from the NotificationHandler interface. Each of these methods accepts the data needed to build a notification message and a list of the notification's recipients.

Adding new notification types

1. Add a method for the new notification type to the NotificationHandler interface.

2. Implement the new methods in every class that implements the interface. Use your IDE to find these. An inexhaustive list:

   • NotificationManager
   • RecipientFinder
   • PonyfmDriver

3. Create a migration to add the new notification type to the activity_types table. Add a constant for it to the Activity class.

4. Ensure you create HTML and plaintext templates, as well as a subclass of BaseNotification for the email version of the notification.

5. Call the new method on the Notification facade from wherever the new notification gets triggered.

6. Implement any necessary logic for the new notification type in the Activity model.

Adding new notification delivery methods

1. Implement a method for sending notifications via the new delivery method in the PonyfmDriver class. Use how email delivery is implemented as a guide.

2. Add UI for subscribing and unsubscribing to the delivery method to the account settings area.

Architectural notes

The notification system is designed around two ideas: being as type-safe as PHP allows it to be, and doing all the processing and sending of notifications asynchronously.

To that end, the NotificationManager class is a thin wrapper around the SendNotifications job. The job calls the notification logic asynchronously to actually send notifications. This job should run on a dedicated queue in production.

The NotificationHandler interface is key to maintaining type safety - it ensures that many classes associated with notifications all support every type of notification. Classes that have logic specific to a notification type implement this interface to ensure that all notification types are handled.

Furthermore, the activity_types table is used to provide referential data integrity in the database - all notifications are linked to an activity record, and each activity record must correspond to a valid activity type. This table is also used for validation of users' subscription preferences.

There's one exception to the use of NotificationHandler - the Activity model. The logic for mapping the data we store about an activity in the database to a notification's API representation had to go somewhere, and using the NotificationHandler interface here would have made this logic a lot more obtuse.

Data flow

1. Some action that triggers a notification calls the NotificationManager facade.

2. An asynchronous job is kicked off that figures out how to send the notification.

3. An Activity record is created for the action.

4. A Notification record is created for every user who is to receive a notification about that activity. These records double as Pony.fm's on-site notifications and cannot be disabled.

5. Depending on subscription preferences, push and email notifications will be sent out as well, each creating their own respective database records. These are linked to a Notification record for unified read/unread tracking.

6. A Notification record is marked read when it is viewed on-site or any other notification type associated with it (like an email or push notification) is clicked.