stellarwp / admin-notice
An object-oriented interface around WordPress' admin notices
Installs: 14 443
Dependents: 0
Suggesters: 0
Security: 0
Stars: 16
Watchers: 10
Forks: 0
Open Issues: 1
Requires
- php: ^5.6 | ^7.0 | ^8.0
Requires (Dev)
- assertwell/shellcheck: ^1.0
- assertwell/wp-core-test-framework: ^0.2.0
- php-stubs/wordpress-tests-stubs: ^5.8
- stellarwp/coding-standards: dev-develop
- stevegrunwell/phpunit-markup-assertions: ^1.3
- szepeviktor/phpstan-wordpress: ^1.0
- yoast/phpunit-polyfills: ^1.0
This package is auto-updated.
Last update: 2024-10-13 17:58:02 UTC
README
This library exposes an object-oriented interface around WordPress' admin notices.
Why is this useful?
Normally, WordPress plugins have to resort to manually constructing admin notices:
function myplugin_render_my_notice() { echo '<div class="notice notice-info"><p>'; esc_html_e('This is the message body.', 'some-plugin'); echo '</p></div>'; } add_action('admin_notices', 'myplugin_render_my_notice');
Unfortunately, this starts getting really messy if you want to conditionally add classes (e.g. .inline
, .notice-alt
, etc.) or check user capabilities. Furthermore, WordPress doesn't provide a consistent way to track whether or not a particular notice has been dismissed, forcing each plugin to come up with its own solution.
This library sets out to solve that problem, giving you a fluent API for constructing and rendering admin notices in your plugins:
use StellarWP\AdminNotice\AdminNotice; $notice = AdminNotice::factory(__('This is the message body.', 'some-plugin'), 'info') ->setCapability('manage_options') ->setDismissible(true) ->queue();
With just a few lines of code, you have a dismissible, info-level notice that will get displayed automatically on "admin_notices", but only if the current user has the "manage_options" capability!
Installation
It's strongly recommended that you install this library as a project dependency via Composer:
$ composer require stellarwp/admin-notice
In order to prevent conflicts between your code and other plugins or themes that might implement this library, it's strongly recommended that you take advantage of PHP Autoloading and do not include_once
or require_once
these files!
Usage
The most basic version of the AdminNotice
class is as follows:
use StellarWP\AdminNotice\AdminNotice; $notice = new AdminNotice('Hello, world!');
💡 To make it easier to construct notices fluently, you may also use the static
AdminNotice::factory()
method, which accepts the same arguments asnew AdminNotice()
.
This $notice
object represents an info-level notice, whose markup will look something like this:
<div class="notice notice-info stellarwp-admin-notice"> <p>Hello, world!</p> </div>
There are two ways of getting the markup for this notice:
$notice->render()
: This method return the markup as a string.$notice->display()
: This method will print the markup to the screen, and is essentially an alias ofecho $notice->render();
💡 The
AdminNotice
class implements the__toString()
magic method, so you may also write something likeecho $notice
.
Admin notice levels
WordPress supports four levels of admin notices:
success
(green color scheme)warning
(yellow color scheme)error
(red color scheme)info
(blue color scheme)
For your convenience, the following constants are available on the AdminNotice
class, to be passed to the second argument of the class constructor:
AdminNotice::TYPE_SUCCESS
AdminNotice::TYPE_WARNING
AdminNotice::TYPE_ERROR
AdminNotice::TYPE_INFO
use StellarWP\AdminNotice\AdminNotice; # Create a success message. AdminNotice::factory('Operation completed sucessfully!', AdminNotice::TYPE_SUCCESS); # Create a warning message. AdminNotice::factory('One or more settings are missing, falling back to defaults.', AdminNotice::TYPE_WARNING); # Create an error message. AdminNotice::factory('You do not have permission to perform this action.', AdminNotice::TYPE_ERROR); # Create an info message (second argument optional) AdminNotice::factory('This is for your information:', AdminNotice::TYPE_INFO);
Rendering admin notices
Now, we need a way to render the notice, typically during the "admin_notices" action.
Admin notices may be queued in a few different ways:
-
Explicitly call
add_action()
with the notice'sdisplay()
method as the callback:add_action('admin_notices, [$notice, 'display']);
-
Call the
queue()
method on the notice itself:AdminNotice::factory('Some message', 'info')->queue();
-
Write your own handler that may work with the notice instance.
Remembering dismissed notices
Often, it can be helpful to remember if a user has dismissed a particular notice. For this reason, AdminNotice::setDismissible()
accepts two arguments:
- Whether or not a notice may be dismissed.
- An optional key for tracking dismissals.
If a dismissible admin notice with a key is rendered, AdminNotice
will automatically enqueue JavaScript to fire an AJAX request when such notices are dismissed: once a user dismisses the notice, the key and timestamp are stored in their user meta.
The only thing the AdminNotice
can't do itself is queue up the AJAX handler. Instead, it's necessary to call StellarWP\AdminNotice\DismissalHandler::listen()
somewhere in your plugin's setup process (wherever you choose to register your hooks).
Example
This example will display the notice with key "some-unique-key" until the user dismisses it.
use StellarWP\AdminNotice\AdminNotice; use StellarWP\AdminNotice\DismissalHandler; // Somewhere in your code, make sure you're listening for the AJAX event. DismissalHandler::listen(); // Create the dismissible admin notice. AdminNotice::factory('This notice may be dismissed') ->setDismissible(true, 'some-unique-key') ->queue();
Checking user capabilities
Often, admin notices are only meant for a small sub-set of users. For example, there isn't much reason to tell all users about a new, premium extension for your plugin if only administrator-level users can install plugins.
For this reason, the AdminNotice
class lets notices be wrapped in a current_user_can()
check:
# Only show this notice if `current_user_can('install_plugins')` returns true. AdminNotice::factory('Hey there, you should install this plugin', 'info') ->setCapability('install_plugins');
The full AdminNotice API
These are all of the methods available for constructing your admin notices:
__construct(string $message[, string $type = 'info'])
Construct a new AdminNotice instance.
Arguments
- string $message
- The body of the admin notice.
- This may contain HTML, and will be run through
wpautop()
andwp_kses_post()
prior to rendering. - string $type
- Optional. The type of notice, one of "success", "error", "warning", or "info". Default is "info".
See also: AdminNotice::factory()
dismissedByUser(?int $user = null): bool
Check to see if this notice has been dismissed by the given user. Will return true if the user has previously dismissed this notice, false otherwise.
Arguments
- ?int $user
- Optional. The user ID. Default is null (the current user).
dismissedByUserAt(?int $user = null): DateTimeImmutable
Retrieve a DateTime object representing when the given user [last] dismissed this notice.
The method will return a DateTimeImmutable
object representing when the notice was dismissed, or NULL
if the user has not dismissed this notice.
Arguments
- ?int $user
- Optional. The user ID. Default is null (the current user).
dismissForUser(?int $user = null): self
Mark a dismissible notice as dismissed by the given user.
This behaves the same as the static dismissNoticeForUser()
method, but doesn't need to be given the notice key (and won't try to dismiss one if no key is present).
Arguments
- ?int $user
- Optional. The user ID. Default is null (the current user).
display(): void
Render and print the admin notice.
queue([int $priority = 10]): self
Queue this admin notice to be displayed on "admin_notices".
Arguments
- int $priority
- Optional. The priority to use with
add_action()
. Default is 10.
render(): string
Render the admin notice.
This method is responsible for all of the logic around how the notice's markup gets built, including whether or not it should show anything at all (based on things like capability checks and/or dismissal history).
setAlt(bool $alt): self
Set whether or not WordPress should use alternate coloring for this notice.
Arguments
- bool $alt
- True if alternate coloring should be used, false otherwise.
setCapability([string $capability = null]): self
Define a capability check that must be satisfied before rendering this notice.
Arguments
- ?string $capability
- A capability that the current user must possess. Passing
NULL
will remove any existing capability requirements.
setDismissible(bool $dismissible[, ?string $key = null]): self
Set whether or not this notice should be dismissible by the user.
Arguments
- bool $dismissible
- Whether or not the notice may be dismissed by the user.
- ?string $key = null
- Optional. A unique key identifying this notice. Default is null (do not track dismissal).
- Once a user has dismissed a notice with this ID, future notices with the same ID will not be rendered.
setInline(bool $inline): self
Specify whether or not a notice should be rendered inline or pulled to the top of the page (default).
Arguments
- bool $inline
- True if the notice should be rendered inline, false otherwise.
static dismissNoticeForUser(string $notice[, ?int = null]): bool
Mark an individual notice as dismissed for the given user ID.
Will return true if the notice has been added to the user's list of dismissed notices, false otherwise.
Arguments
- string $notice
- The admin notice's dismissible key.
- int $user
- Optional. The user ID. Default is null (the current user).
static factory(string $message[, string $type = 'info']): AdminNotice
This method is an alias for the class constructor (and accepts the same arguments), making it easier to write fluent strings.
Both notices in the following are equivalent:
# Using the constructor directly requires extra parentheses. (new AdminNotice('Some message', 'info')) ->setInline(true) ->queue(); # The ::factory() method removes this constraint. AdminNotice::factory('Some message', 'info') ->setInline(true) ->queue();
Contributing
If you're interested in contributing to the project, please see our contributing documentation.
License
This library is licensed under the terms of the MIT license.