Feature Project Proposal: WP Notify

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, pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party developers and CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. have been using adminadmin (and super 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 HTMLHTML HyperText Markup Language. The semantic scripting language primarily used for outputting content in web browsers.. 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 extensibleExtensible This is the ability to add additional functionality to the code. Plugins extend the WordPress core software. 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 JSONJSON JSON, or JavaScript Object Notation, is a minimal, readable format for structuring data. It is used primarily to transmit data between a server and web application, as an alternative to XML.).
  • 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 APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. that allows for easy manipulations the way plugin developers are accustomed to.
  • REST APIREST API The REST API is an acronym for the RESTful Application Program Interface (API) that uses HTTP requests to GET, PUT, POST and DELETE data. It is how the front end of an application (think “phone app” or “website”) can communicate with the data store (think “database” or “file system”) https://developer.wordpress.org/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 JavaScriptJavaScript JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. https://www.javascript.com/. 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 GutenbergGutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. https://wordpress.org/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 SlackSlack Slack is a Collaborative Group Chat Platform https://slack.com/. The WordPress community has its own Slack Channel at https://make.wordpress.org/chat/.
  • Providing a webhook to feed notifications from third-party services like GitHubGitHub GitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged be the repository owner. https://github.com/ 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 PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 5.6.20 or higher 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 UIUI User interface/UXUX User experience 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 TracTrac An open source project by Edgewall Software that serves as a bug tracker and project management tool for WordPress. ticketticket Created for both bug reports and feature development on the bug tracker. 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.