| Notifications Portal |
|---|
-logo.svg){kind=logo} |
| About |
| Documentation |
| Developer documentation |
| v · d · e |
MediaWiki 1.44 introduces a built-in notifications framework, created by theMediaWiki Platform Team. The interfaces will bestabilized inMediaWiki 1.45.
The framework does not provide any means of delivering or displaying notifications, which are instead provided by pluggable handlers defined by extensions. The only currently existing handler is provided by theEcho extension, which you already know and love.
TheEnotif feature will be reimplemented on top of the new notifications (as of 1.44 this is still in progress).
The main purpose of pulling the framework into core, without actually implementing any handlers there, is to allow MediaWiki itself to emit notifications for common events, such as a page being edited or a user logging in from a new device. Since the notifications were previously implemented only in Echo, and MediaWiki core can not depend on extensions, we had to awkwardly implement them in Echo or extensions depending on Echo, or use bespoke systems like Enotif.
For extensions that already use Echo, it allows omitting checks for Echo being installed, and provides a more type-safe interface thanEvent::create(). We hope that the middleware system will also prove to be a more reliable way of overriding other extensions' notifications than the current variety of hooks defined in Echo.
To send a notification, useMediaWikiServices::getNotificationService()->notify( ... ).
Example use from the Thanks extension:
$this->notifications->notify(newWikiNotification('edit-thank',$title,$user,[$type.'id'=>$id,'source'=>$source,'excerpt'=>$excerpt,'revcreation'=>$revcreation,]),newRecipientSet($recipient));
This replaces theEvent::create() method from Echo, with the first three parameters ofWikiNotification corresponding to thetype,title andagent parameters described there, and theRecipientSet defining users to be notified. The array of additional data corresponds to theextra parameter.
In order for this notification to be displayed, you still need to integrate with Echo, as described inExtension:Echo/Creating a new notification type#Defining the event and#Creating a presentation model.
If that sounds like too much work, you can send a simple notification as follows:
$this->notifications->notifySimple(MessageValue::new('my-message-key')->params('my parameter')->numParams(123),/* UserIdentity */$recipient);
This only allows displaying a single message, without most features provided by Echo, such as icons, actions and support for user preferences.
When migrating an existing notification type using Echo to the new system, code using customuser-locators needs to be first changed to use the default locator and pass recipients using the optionalRecipientSet parameter ofEvent::create(). If your event usedlocateFromEventExtra and passed user IDs, you can create aRecipientSet from the user objects. If your event used another locator, you'll need to call the locator function and create aRecipientSet yourself.
Event::create([...],newRecipientSet($recipient));
You may want to do such change in two steps (add new, thenremove old), to ensure that events are not lost while the change is being deployed. Echo will filter out duplicate recipients.More migration examples.
Once you have the event creation in that form, converting it to useNotificationService is an easy replacement (example change in the Thanks extension).
Extensions that wish to modify or abort notifications sent by other extensions (or MediaWiki itself) before they're processed by the handlers can register middleware using theNotificationMiddleware extension.json property. (example use cases here)
A sampleAbortEmailNotification hook that filters stops Watchlist notification from happening looked like this:
/** Hook: AbortEmailNotification */publicstaticfunctiononAbortEmailNotificationReview(User$editor,Title$title,RecentChange$rc):bool{return$rc->getAttribute('rc_log_type')!=='translationreview';}
To migrate this code into the Middleware approach, there are two steps required:
First, create a new Middleware class that is responsible for filtering such Notifications:
classFilterTranslationReviewNotificationsMiddlewareextendsFilterMiddleware{protectedfunctionfilter(NotificationEnvelope$envelope):bool{$notification=$envelope->getNotification();if($notificationinstanceofRecentChangeNotification){$logType=$notification->getRecentChange()->getAttribute('rc_log_type');return$logType==='translationreview'?self::REMOVE:self::KEEP;}returnself::KEEP;}}
and register the new middleware in extension.json:
"NotificationMiddleware":[{"class":"FilterTranslationReviewNotificationsMiddleware"}],
Examples
Extensions that wish to deliver or display notifications can register handlers using theNotificationHandlers extension.json property. This is used by Echo to implement the real notification functionality. You probably don't want to replace Echo as the wildcard handler, but you can register handlers for your own notification types (overriding Echo entirely).