PHPackages yahnis-elsts/admin-notices - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. yahnis-elsts/admin-notices ActiveLibrary[Utility & Helpers](/categories/utility) yahnis-elsts/admin-notices ========================== A utility library for WordPress plugins that makes it easier to create admin notices. Supports persistently dismissible notices. v1.1(7y ago)311.8k7[1 issues](https://github.com/YahnisElsts/admin-notices/issues)MITPHPPHP >=5.3.0 Since Mar 20Pushed 1y ago3 watchersCompare [ Source](https://github.com/YahnisElsts/admin-notices)[ Packagist](https://packagist.org/packages/yahnis-elsts/admin-notices)[ RSS](/packages/yahnis-elsts-admin-notices/feed)WikiDiscussions master Synced yesterday READMEChangelog (2)DependenciesVersions (3)Used By (0) Easy Admin Notices ================== [](#easy-admin-notices) A PHP utility library for WordPress plugins that helps create admin notices. Highlights ---------- [](#highlights) - Fluent interface. - [Persistently dismissible notices](#persistentlydismissiblescope) with optional dismissal duration. - Show notices [on specific pages](#onpagescreenid). - Show notices to users who have [a specific capability](#requiredcapcapability). Requirements ------------ [](#requirements) - PHP 5.3 or later. - WordPress 4.2 or later. Installation ------------ [](#installation) Install with Composer: ``` composer require "yahnis-elsts/admin-notices" ``` Alternatively, you can install it manually: 1. Download [the latest release](https://github.com/YahnisElsts/admin-notices/releases/latest). 2. Move the `admin-notices` directory to your plugin. 3. Load the library: ``` require '/path/to/admin-notices/AdminNotice.php'; ``` A note on load order: To ensure that persistently dismissible notices will work correctly, you should `require` the library *before* the `admin_init` action. For example, you can put the `require` in a `plugins_loaded` hook, or simply at the top of your plugin. Usage ----- [](#usage) Basic example: ``` use \YeEasyAdminNotices\V1\AdminNotice; AdminNotice::create() ->success('Hello world!') ->show(); ``` Result: [![Basic admin notice](https://cloud.githubusercontent.com/assets/2527434/24096796/c5d87d28-0d6b-11e7-82ad-519a8b24ece8.png)](https://cloud.githubusercontent.com/assets/2527434/24096796/c5d87d28-0d6b-11e7-82ad-519a8b24ece8.png) You don't have to put this code in a hook. The `show()` method is smart. It checks if the `admin_notices` action was already executed and either displays the notice immediately or adds a new `admin_notices` hook that will display the notice when appropriate. It also checks any capability requirements and page filters before actually showing the notice (see [Preconditions](#preconditions)). ### Type shortcuts [](#type-shortcuts) WordPress comes with several built-in CSS classes for different types of admin notices. You can use the following shortcut methods to simultaneously set the notice type and the contents of the notice. ##### `success([$message])` [](#successmessage) ``` AdminNotice::create()->success('Success')->show(); ``` [![Success notice](https://cloud.githubusercontent.com/assets/2527434/24096800/c5ee4ebe-0d6b-11e7-9956-91a73e656539.png)](https://cloud.githubusercontent.com/assets/2527434/24096800/c5ee4ebe-0d6b-11e7-9956-91a73e656539.png) ##### `error([$message])` [](#errormessage) ``` AdminNotice::create()->error('Error')->show(); ``` [![Error notice](https://cloud.githubusercontent.com/assets/2527434/24096799/c5dd524e-0d6b-11e7-9fb8-d9164821ed43.png)](https://cloud.githubusercontent.com/assets/2527434/24096799/c5dd524e-0d6b-11e7-9fb8-d9164821ed43.png) ##### `warning([$message])` [](#warningmessage) ``` AdminNotice::create()->warning('Warning')->show(); ``` [![Warning notice](https://cloud.githubusercontent.com/assets/2527434/24096802/c5f77174-0d6b-11e7-8190-101c6405f478.png)](https://cloud.githubusercontent.com/assets/2527434/24096802/c5f77174-0d6b-11e7-8190-101c6405f478.png) ##### `info([$message])` [](#infomessage) ``` AdminNotice::create()->info('Information')->show(); ``` [![Informational notice](https://cloud.githubusercontent.com/assets/2527434/24096803/c6427d40-0d6b-11e7-9bb2-0f9d28a3df1a.png)](https://cloud.githubusercontent.com/assets/2527434/24096803/c6427d40-0d6b-11e7-9bb2-0f9d28a3df1a.png) ### Content [](#content) Instead of passing a string to one of the type-specific methods, you can set the contents of the notice by calling one of the following methods. ##### `text($message)` [](#textmessage) Set the contents of the notice to a text string. `text()` will escape HTML special characters like ``, `&` and so on. Example: ``` AdminNotice::create() ->info() ->text('/* This will be displayed as plain text. */') ->show(); ``` [![Text escaping](https://cloud.githubusercontent.com/assets/2527434/24096797/c5d935c4-0d6b-11e7-81a6-e94c88a53096.png)](https://cloud.githubusercontent.com/assets/2527434/24096797/c5d935c4-0d6b-11e7-81a6-e94c88a53096.png) ##### `html($arbitraryHtml)` [](#htmlarbitraryhtml) Set the contents of the notice to a HTML string. Unlike `text()`, this method does not perform any escaping or encoding. ``` AdminNotice::create() ->info() ->html('Tip: Go to Settings -> My Plugin to configure the plugin.') ->show(); ``` [![HTML content](https://cloud.githubusercontent.com/assets/2527434/24096798/c5dbf0de-0d6b-11e7-9c5a-893ef7d568e0.png)](https://cloud.githubusercontent.com/assets/2527434/24096798/c5dbf0de-0d6b-11e7-9c5a-893ef7d568e0.png) ##### `rawHtml($arbitraryHtml)` [](#rawhtmlarbitraryhtml) Usually, the contents of a notice are wrapped in a single paragraph (``) tag. To prevent this wrapping, use `rawHtml()` to set the notice content. This is useful if you want to use complex HTML or to display a long message where one paragraph is not enough. ``` AdminNotice::create() ->rawHtml('First paragraphSecond paragraph') ->show(); ``` [![Raw HTML content](https://cloud.githubusercontent.com/assets/2527434/24096794/c5af9ade-0d6b-11e7-9e96-9b5e174dbaa0.png)](https://cloud.githubusercontent.com/assets/2527434/24096794/c5af9ade-0d6b-11e7-9e96-9b5e174dbaa0.png) ### Dismissible notices [](#dismissible-notices) ##### `dismissible()` [](#dismissible) Add an "(x)" icon to the notice. Clicking the icon will hide the notice. However, this doesn't prevent the notice from reappearing in the future. Use `persistentlyDismissible()` for that. ``` AdminNotice::create() ->text('You can hide this notice by clicking the "(x)" =>') ->dismissible() ->show(); ``` [![Dismissible notice (not persistent)](https://cloud.githubusercontent.com/assets/2527434/24096795/c5d3e0a6-0d6b-11e7-87b3-2ca7b1f143aa.png)](https://cloud.githubusercontent.com/assets/2527434/24096795/c5d3e0a6-0d6b-11e7-87b3-2ca7b1f143aa.png) ##### `persistentlyDismissible([$scope, $duration])` [](#persistentlydismissiblescope-duration) Make the notice persistently dismissible. When the user dismisses the notice, the library stores a flag in the database that prevents the notice from showing up again. Persistently dismissible notices must have a unique ID. The `$scope` parameter controls whether clicking "(x)" will hide the notice for everyone or just for the current user. The supported values are: - `AdminNotice::DISMISS_PER_SITE` - hide the notice site-wide. This is the default. - `AdminNotice::DISMISS_PER_USER` - hide the notice only for the current user. Example: ``` AdminNotice::create('my-notice-id') ->persistentlyDismissible(AdminNotice::DISMISS_PER_SITE) ->success('This notice can be permanently dismissed.') ->show(); ``` [![Persistently dismissible notice](https://cloud.githubusercontent.com/assets/2527434/24096801/c5f5ccb6-0d6b-11e7-8bd9-42c90e974446.png)](https://cloud.githubusercontent.com/assets/2527434/24096801/c5f5ccb6-0d6b-11e7-8bd9-42c90e974446.png) The `$duration` parameter controls how long (in seconds) the notice will be considered dismissed for. By default, notices will be dismissed permanently. Example: ``` AdminNotice::create('my-notice-id') ->persistentlyDismissible(AdminNotice::DISMISS_PER_SITE, WEEK_IN_SECONDS) ->success('This notice can be dismissed for 1 week.') ->show(); ``` Notes: - You must load `AdminNotice.php` before the `admin_init` action to make sure that the default AJAX handlers get set up correctly. - It's safe to call `show()` on a dismissed notice. It won't display the notice, and it won't throw an error either. ##### `dismiss([$duration])` [](#dismissduration) Persistently dismiss the notice. Only works on notices that have been flagged as `persistentlyDismissible()`. The `$duration` parameter controls how long (in seconds) the notice will be considered dismissed for. By default, the duration is the same as the duration passed to `persistentlyDismissible()`. You can also pass `AdminNotice::DISMISS_PERMANENTLY` to dismiss the notice permanently. ##### `undismiss()` [](#undismiss) Restore a previously dismissed notice. ##### `isDismissed() : boolean` [](#isdismissed--boolean) Check if the notice has been dismissed. ##### `AdminNotice::cleanUpDatabase($prefix)` [](#adminnoticecleanupdatabaseprefix) Delete all "this notice is dismissed" flags that have the specified ID prefix from the database. If you're using persistently dismissible notices, it's a good idea to call this function when your plugin is uninstalled. For example, if your notice IDs start with `myplugin-`, you can remove the database entries like this: ``` AdminNotice::cleanUpDatabase('myplugin-'); ``` ### Preconditions [](#preconditions) These methods control **where** notices will appear and **who** will be able to see them. ##### `onPage($screenId)` [](#onpagescreenid) Show the notice only on the specified admin page(s). `$screenId` can be either the screen ID of a page (i.e. a string), or an array of screen IDs. See [Admin Screen Reference](https://codex.wordpress.org/Plugin_API/Admin_Screen_Reference) for a list of screens and their IDs. In the case of plugin and theme admin pages, the screen ID is usually the same as the value returned by the `add_*_page()` function. Example: ``` AdminNotice::create() ->info() ->text('This message will only appear on the "Plugins -> Installed Plugins" page') ->onPage('plugins') ->show(); add_action('admin_menu', function() { $id = add_options_page( 'Example', 'Example', 'manage_options', 'example-admin-page', '__return_false' ); AdminNotice::create() ->info() ->text('This will appear on "Settings -> Example"') ->onPage($id) ->show(); }); ``` ##### `requiredCap($capability)` [](#requiredcapcapability) Show the notice only to users who have the specified `$capability`. ### Show now or later [](#show-now-or-later) After creating a notice, call one of these methods to display it. ##### `show()` [](#show) Automagically show the notice on the current page when all preconditions are met. ##### `showOnNextPage()` [](#showonnextpage) Show the notice on the next admin page that's visited by the current user. The notice will be shown only once. This method is useful for plugin activation hooks, redirects, and other situations where you can't display a notice immediately for whatever reason. The library will store the notice in the database. It will display the notice the next time that the `admin_notices` action is called in the context of the current user, whether happens during this page load or the next one, or a week later. ##### `outputNotice()` [](#outputnotice) Immediately display the notice. This method bypasses any checks and preconditions and just outputs the notice directly. It's mainly intended for debugging. ### Health Score 37 — LowBetter than 81% of packages Maintenance26 Infrequent updates — may be unmaintained Popularity34 Limited adoption so far Community15 Small or concentrated contributor base Maturity59 Maturing project, gaining track record Bus Factor1 Top contributor holds 85.3% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~687 days Total 2 Last Release 2701d ago ### Community Maintainers ![](https://avatars.githubusercontent.com/u/2527434?v=4)[Yahnis Elsts](/maintainers/YahnisElsts)[@YahnisElsts](https://github.com/YahnisElsts) --- Top Contributors [![YahnisElsts](https://avatars.githubusercontent.com/u/2527434?v=4)](https://github.com/YahnisElsts "YahnisElsts (29 commits)")[![benignant](https://avatars.githubusercontent.com/u/19580651?v=4)](https://github.com/benignant "benignant (4 commits)")[![mickaelperrin](https://avatars.githubusercontent.com/u/5844226?v=4)](https://github.com/mickaelperrin "mickaelperrin (1 commits)") ### Embed Badge ![Health badge](/badges/yahnis-elsts-admin-notices/health.svg) ``` [![Health](https://phpackages.com/badges/yahnis-elsts-admin-notices/health.svg)](https://phpackages.com/packages/yahnis-elsts-admin-notices) ``` ### Alternatives [marcelog/ding PHP Dependency Injection based on Spring(tm), with Aspect Oriented Programming, MVC 1192.1k](/packages/marcelog-ding)[kegi/netscape-cookie-file-handler Netscape Cookie File Handler 2311.3k](/packages/kegi-netscape-cookie-file-handler)[handleglobal/nova-nested-form A Laravel Nova package that allows you to create/update/delete nested related fields from a parent form. 381.9k](/packages/handleglobal-nova-nested-form)[hanifhefaz/dcter A composer package used to convert Jalali, Hijri, Gregorian and Julian dates to each others. Plus some extra utilities and helpers. 332.0k](/packages/hanifhefaz-dcter)[imarc/opus Multi-framework asset and module packaging for composer 1112.4k3](/packages/imarc-opus) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)