Manual:Notifications
MediaWiki 1.44 introduces a built-in notifications framework, created by the MediaWiki Platform Team.
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 the Echo extension, which you already know and love.
The Enotif feature will be reimplemented on top of the new notifications (as of 1.44 this is still in progress).
Benefits
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 than Event::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.
Sending notifications
To send a notification, use MediaWikiServices::getNotificationService()->notify( ... ).
Example use from the Thanks extension:
$this->notifications->notify(
new WikiNotification( 'edit-thank', $title, $user, [
$type . 'id' => $id,
'source' => $source,
'excerpt' => $excerpt,
'revcreation' => $revcreation,
] ),
new RecipientSet( $recipient )
);
This replaces the Event::create() method from Echo, with the first three parameters of WikiNotification corresponding to the type, title and agent parameters described there, and the RecipientSet defining users to be notified. The array of additional data corresponds to the extra parameter.
In order for this notification to be displayed, you still need to integrate with Echo, as described in Extension:Echo/Creating a new notification type#Defining the event and #Creating a presentation model.
Simple notifications
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.
Migrating from Echo
When migrating an existing notification type using Echo to the new system, code using custom user-locators needs to be first changed to use the default locator and pass recipients using the optional RecipientSet parameter of Event::create(). If your event used locateFromEventExtra and passed user IDs, you can create a RecipientSet from the user objects. If your event used another locator, you'll need to call the locator function and create a RecipientSet yourself.
You may want to do such change in two steps (add new, then remove 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 use NotificationService is an easy replacement (example change in the Thanks extension).
Modifying notifications
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 the NotificationMiddleware extension.json property. (example use cases here)
Migrating from Echo
Handling notifications
Extensions that wish to deliver or display notifications can register handlers using the NotificationHandlers 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).