mirror of
https://github.com/Poniverse/Pony.fm.git
synced 2024-11-26 23:07:59 +01:00
123 lines
4.8 KiB
Markdown
123 lines
4.8 KiB
Markdown
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`](app/Contracts/NotificationHandler.php)
|
|
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:
|
|
|
|
```php
|
|
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`](../app/Contracts/NotificationHandler.php) 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`](../app/Contracts/NotificationHandler.php)
|
|
interface.
|
|
|
|
2. Implement the new methods in every class that implements the
|
|
interface. Use your IDE to find these. An inexhaustive list:
|
|
|
|
- [`NotificationManager`](../app/Library/Notifications/NotificationManager.php)
|
|
- [`RecipientFinder`](../app/Library/Notifications/RecipientFinder.php)
|
|
- [`PonyfmDriver`](../app/Library/Notifications/PonyfmDriver.php)
|
|
|
|
3. Create a migration to add the new notification type to the `activity_types`
|
|
table. Add a constant for it to the [`Activity`](../app/Models/Activity.php)
|
|
class.
|
|
|
|
3. Ensure you create HTML and plaintext templates, as well as a subclass of
|
|
[`BaseNotification`](../app/Mail/BaseNotification.php) for the email version
|
|
of the notification.
|
|
|
|
4. Call the new method on the `Notification` facade from wherever the
|
|
new notification gets triggered.
|
|
|
|
5. Implement any necessary logic for the new notification type in the
|
|
[`Activity`](../app/Models/Activity.php) model.
|
|
|
|
|
|
Adding new notification delivery methods
|
|
----------------------------------------
|
|
|
|
1. Implement a method for sending notifications via the new delivery method in
|
|
the [`PonyfmDriver`](../app/Library/Notifications/PonyfmDriver.php) 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`](../public/templates/account/settings.html).
|
|
|
|
|
|
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`](../app/Library/Notifications/NotificationManager.php)
|
|
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`](../app/Contracts/NotificationHandler.php)
|
|
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`](../app/Models/Activity.php) 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.
|