This detailed proposal was originally drafted by @schlessera, who unfortunately does not have the resources to commit to executing the project. I am however thankful that he has agreed to assist, in an advisory role.

Introduction

WordPress is currently lacking a fundamental mechanism: sending notifications to users to give them feedback about state changes in the system. Traditionally, plugin developers and Core have been using admin notices for this purpose, but this solution is lackluster at best and comes with a lot of disadvantages:

• They are rendered into the normal working area in the dashboard and can even push the actual page content below the fold.
• The user has no control over how or when they want to deal with them, therefore they see them in a mostly negative fashion.
• They are nothing more than printed HTML. Because they lack any kind of structure, it is not possible to manipulate them in an automated fashion.
• Their persistence is not regulated, which leads to many different implementations as well as cruft in the database.

For the above reasons, there’s a general consensus that admin notice are not up to the task and need a more robust replacement that can deal with current and future notification needs.

I hereby want to officially kickstart a Feature Project called “WP Notify“.

Project Scope

The initial project will cover an extensible backend implementation as well as a single frontend use case.

A. Backend implementation

The backend implementation will cover the following elements:

• An object model that is extensible as well as serializable (to JSON).
• A persistence abstraction that comes with an initial WPDB implementation.
• A background queue that processes notifications to distribute them across channels, for use cases where this is a costly operation, like sending them through email.
• A simplified procedural API that allows for easy manipulations the way plugin developers are accustomed to.
• REST API controllers that provide endpoints to manage the notification from the frontend.

B. Frontend use case

The frontend use case will cover the following elements:

• An admin bar integration that shows notification state and opens a panel to read and dismiss current notifications.
• An settings page that lets the user control which notifications to show/hide in the admin bar and which notifications to forward through email.

Technical Requirements

• Objects must be serializable to JSON in such a way that it can be sent to the client, either as a localized JavaScript snippet or as a REST API response.
• A notification can have one or more recipients, which can be users, roles or a mixture of both.
• A recipient can configure the channel(s) they want to receive the notifications in, on a “per-group” basis.
• Distribution across channels is not directly coupled to the frontend request, but works as a background queue.
• The admin bar integration needs to build on top of the work done with Gutenberg and use a reactive interface powered by the REST API.

Some Clarifications

Did this just come out of the blue?

No, the need for a notification subsystem has been identified a long time ago. Current discussions have been centralized in the Trac ticket #43484.

Why does this document talk about a “single frontend use case”? Does the proposal not already cover everything anyway?

No, having a sort of “admin bar hub” to manage your notifications is indeed only one potential use of the the notifications subsystem. The way it is currently planned, it could easily have other use cases, like the following examples:

• Forwarding notifications to a webhook, for integrations into third-party services like Slack
• Providing a webhook to feed notifications from third-party services like GitHub into WordPress
• Showing notifications in a management system like cPanel or ManageWP
• Integrating notifications contextually into other parts of the admin experience in a targeted way
• Providing a “feed” view/endpoint
• Letting other servers or tools send notifications to WordPress users/roles over the REST API, like a cron job completing a shell maintenance task
• Attaching server notification systems like notify-send or growl to your WordPress dashboard
• …

Why have so many complex moving pieces? Isn’t this called over-engineering?

Complex solutions can easily be adapted to fit simpler needs, while the opposite is not true. As you can see with the current admin notices, a simplistic solution that tries to solve a complex problem causes more harm than good, as you cannot just get rid of inherent complexity. On the contrary, a solution that is not properly adapted will cause additional complexity just because of the amount of side-effects it will generate.

I am certain that building a notifications mechanism for an entire platform like WordPress that fits the entire spectrum of scenarios from simple blogs to enterprise-grade custom solutions is inherently complex. An abstraction allows us to put the main extensibility points in place to stay future-proof and then concentrate on the few basic implementations we need for 80% use cases… without having locked out developers with more exotic needs and while at the same time leaving the solution open to creative improvements in the future.

What is this “simplified procedural API” all about?

While building an extensible object model will allow us to extend the implementations in a safe way in the future, it also comes with more complex usage when interacted with directly.

That is why we should include a simplified procedural wrapper around the object model that mimics the way plugin & theme developers are used to work with WordPress.

As an example, instead of creating an instance of a factory first, to then retrieve a base notification with a simple message and a single recipient to it, we could have a simplified wrapper that looks like this:

// Create a new notification for the current user.
wp_notify( 'MyBackupPlugin', get_current_user_id(), 'Backup completed!' );

// Mark a specific notification as read.
get_notification( $notification_id )->mark_as_read();

These procedural functions come with a default setup that can be controlled via actions & filters.

Such a simplified layer allows us to have the best of both worlds: robust and extensible behind the scenes, and simple and intuitive facing the user.

So we’re building a complex object model and then wrap it with simplified functions. This is not how WordPress code is usually done…

Indeed. Given that this project is mostly isolated and can be approached in an unencumbered way, it offers the perfect opportunity to improve the general way WordPress Core code is done. It should demonstrate that it is possible to get the combined benefits of both an extensible object model that is robust to work with as well as an intuitive public-facing API that provides a low barrier of entry.

There is a lot of momentum right now on the WordPress Core developer front. But general coding conventions are still based in large parts on what we inherited from the project’s roots. This project can help define a new set of WordPress-specific coding patterns that are not tied to the compromised patterns we inherited from the PHP 4 era.

Yes, this is not how WordPress code is usually done … yet! But we can change that!

Wasn’t there a similar Feature Project already?

You’re referring to the post by John Blackbourn that he wrote in 2016. That project proposal never really got off the ground, and I got confirmation from John that it is abandoned and should hopefully be replaced, as the need for it is still there.

Call for Volunteers

If the above sounds like something you would like to contribute to, please either write a brief comment below this post, with the area you are interested in and the skills you can offer.

Alternatively, you can join the discussions on Slack in the #feature-notifications channel or on Trac ticket #43484.

This project covers a lot of different areas, like advanced backend code, scalable database gymnastics, reactive JavaScript code and dynamic UI/UX design.

All help is welcome, but please be aware that different topics will be in focus at different stages of the project.

Next Steps

There have already been a number of interested parties on the Trac ticket or in the #feature-notifications channel and I look forward to your feedback, comments and suggestions. By the 19th of August I plan to have an initial project kick off meeting scheduled, so that we can set up a plan of how best to move forward.