Extension:TimedNotify

TimedNotify provides a time-based notification system for Echo. Time-based notifications are notifications that are not explicitly triggered by an action, but are instead sent out (periodically) when certain criteria are met. The canonical example of time-based notifications are reminders.

Configuration
The following configuration options are available:


 * (default: ) - determines the run rate of the notifier
 * (default: ) - whether to run the notifications in a deferred update
 * (default: ) - the number of days to retain pushed notifications
 * (default: ) - which notifiers to disable

$wgTimedNotifyRunRate
This configuration parameter determines how often to run the notifications. Calculating which notifications to send out and to whom is expensive. The notifications are therefore only calculated approximately once every  requests. Thus, if you set your run rate to, the probability of running the notifications is 1 in 100 for every request. Setting this to a lower number will increase performance, as the notifications have to be calculated less often, but it will decrease the timeliness of the notifications. That is, notifications may arrive later than expected. It is recommended to keep this value between   and  , depending on the size of your wiki. For smaller wiki's, this value should be greater than for large wiki's.

If you don't want notifications to run on web requests at all, you can set the run rate to. In this case  should be run periodically.

It should be a number between  inclusive and   inclusive. The default value is.

$wgTimedNotifyRunDeferred
This configuration parameter determines whether to run the notifications in a deferred update. If this parameter is set to, notifications are calculated after a response has already been sent to the browser. This calculation will therefore not impact the load time of the wiki. Unless you have a specific reason to set this to, you generally should not have to change this.

It should be a boolean. The default value is.

$wgTimedNotifyPushedNotificationRetentionDays
This configuration parameter specifies the number of days to remember pushed notifications. In order to prevent duplicate notifications for the same event, TimedNotify keeps track for which events it has already sent out notifications in a database table. To prevent this table from growing extremely large, old notifications are occasionally purged from the table. This configuration options specifies the minimum age in days before a notification is purged from this table.

It should be an integer. The default value is.

$wgTimedNotifyDisabledNotifiers
This configuration parameter specifies which notifiers to disable. It should be an array of booleans, where the key is the name of the notifier, and the value is  to disable the notifier. By default, the array is empty and all notifiers are enabled.

It should be an array. The default value is.

Adding a new notification type
Adding a new time-based notification type is relatively easy and quite similar to adding a new notification type to Echo directly.

Introduction to how time-based notifications work
Time-based notifications are notifications that are not explicitly triggered by an action. This means that the calculation to determine which time-based notifications need to be sent out needs to happen periodically. How often this happens is based on, which is explained above.

Since the notifications are (re-)calculated periodically, we need to make sure we do not push the same notification twice. To solve this, a notification can be annotated with a unique ID. The extension guarantees that a notification is only pushed if no notification with the same ID has been pushed before.

For example, suppose we want to create a notification that reminds a user that their moderation status is to expire in less than 30 days. The condition for this "event" is true for 30 days, but the notification should only be sent out once. Therefore, we push a notification annotated with the ID, where   is the expiration date of the user's moderation status. The expiration date will not change (and if it does, the notification should be sent out again when applicable), and therefore the notification will only be sent out once.

Notification definition
Each notifier must be defined in a class. This class must extend the base  class, and may implement the following methods:

Notification format
A notification should be an array with the following keys:

Notification registration
Notification registration happens in the method that corresponds to the  hook. This hook includes a single variable,  and contains a list of classes that extend. You must add your new notifiers through this hook. For example:

Walkthrough: Creating a new notification type
Suppose we want to create an extension that notifies the user whenever their moderation status is about to expire. This section will demonstrate how to build such an extension using TimedNotify. This section will omit some details of creating an extension, and will only focus on the parts that interact with TimedNotify.

Creating the class
We start by creating a new class that extends :

Next, we implement the  to register our notifier: