Admin Notices Service

The Admin Notices Service is again a multi-handler service but this time it implements the output action method. If you've used WordPress before, you've probably come across admin notices before such as the ones exemplified in this article. This service attempts to standardize the registration and output of those notices,

This service is probably the most complicated one we have so it will be a bit of a challenge to explain how it works, but we'll try our best. The first thing you should understand is that notices have different flavors. A notice is actually quite a complicated abstraction -- at a minimum it has a type (supported notice types are stored comfortably in the AdminNoticeTypesEnum class) and a text. We'll call those simple notices. A notice, however, can also be dismissed by the user. Those are dismissible notices. These are the 2 types of notices supported by default but you can create your own custom notice by simply implementing the AdminNoticeInterface interface.

Each notice type has a corresponding handler. Simple notices need a handler that is simply capable of outputting their HTML whereas dismissible notices require a handler that can handle the dismiss request. Subsequently those are the two handlers pre-packaged with the module (here), but you can always implement your own by implementing the AdminNoticesHandlerInterface interface.

As you might've guessed, by default, both handlers are automagically registered with the service on instantiation. If you've looked over the code so far, you probably noticed that multi-handler services use a memory store for storing the registered handlers. The admin notices service does that too, but the memory store is actually 2-dimensional this time! That is because on top of the handlers, the service also keep a list of stores and registers by default a memory store (dynamic), an options store (options), and a user-meta store (user-meta).

That is because notices have different scopes and lifecycles. For example, an error notice for an employee that tried to perform an action (s)he is not authorized could be stored in the dynamic store if it's not that important and should disappear on next page load or it could be stored in the user-meta store if it's dismissible and needs to stick around until the user has actively dismissed it.

Another example will become clear when we dig deeper into the dependencies service. Certain dependencies are mandatory (like WooCommerce being active for a WooCommerce extension plugin) or they could be optional (like a recommendation for certain PHP settings). Mandatory dependencies need to be checked on every request so these notices are probably simply stored in the memory store and added again on each request. Optional dependencies, however, would output a dismissible notice and will not prevent the plugin from being active if an admin has dismissed said notice. Therefore, these notices would go into the options store and be shared by all admins -- if one dismisses it, it's dismissed for all.

The admin notices service provides the following public methods:

• add_notice for adding a notice to a given store

• get_notice for retrieving a notice from a given store

• update_notice for updating a notice in a given store

• remove_notice for removing a notice from a given store

The output of the notices happens on the WP hook admin_notices. For obvious reasons, the methods update_notice and remove_notice don't do much after the aforementioned hook is executed.

How to use the service

The recommended way is by using the SetupAdminNoticesTrait setup trait. You are free, however, to make use of any traits and interfaces available in the admin notices namespace.