{"id":34744660,"url":"https://github.com/stellarwp/admin-notices","last_synced_at":"2026-03-13T23:31:53.817Z","repository":{"id":255409253,"uuid":"821581367","full_name":"stellarwp/admin-notices","owner":"stellarwp","description":"A handy package for easily displaying admin notices in WordPress with simple to complex visibility conditions","archived":false,"fork":false,"pushed_at":"2025-07-10T17:45:32.000Z","size":129,"stargazers_count":12,"open_issues_count":3,"forks_count":0,"subscribers_count":4,"default_branch":"main","last_synced_at":"2026-03-13T00:14:28.682Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stellarwp.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-06-28T21:59:54.000Z","updated_at":"2026-02-12T08:42:16.000Z","dependencies_parsed_at":"2024-11-15T23:18:00.214Z","dependency_job_id":"e3f8434c-a36b-4b7e-96b5-5425ebe230dc","html_url":"https://github.com/stellarwp/admin-notices","commit_stats":null,"previous_names":["stellarwp/admin-notices"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/stellarwp/admin-notices","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stellarwp%2Fadmin-notices","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stellarwp%2Fadmin-notices/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stellarwp%2Fadmin-notices/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stellarwp%2Fadmin-notices/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stellarwp","download_url":"https://codeload.github.com/stellarwp/admin-notices/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stellarwp%2Fadmin-notices/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30479342,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-13T20:45:58.186Z","status":"ssl_error","status_checked_at":"2026-03-13T20:45:20.133Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-12-25T04:29:59.469Z","updated_at":"2026-03-13T23:31:53.810Z","avatar_url":"https://github.com/stellarwp.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Introduction\n\nDisplaying notices within the WordPress admin is a highly common need in plugins. Displaying notices\nis not difficult, but it gets tedious when wanting to conditionally display notices based on\nconditions such as user capability, the current screen, date range, and so forth.\n\nThis library is intended to provide a simple, readable way for developers to conditionally display\nstandard or highly customized notices within the WordPress admin.\n\n# How to use\n\n## Installation\n\nIt's recommended that you install Admin Notices as a project dependency\nvia [Composer](https://getcomposer.org/):\n\n```bash\ncomposer require stellarwp/admin-notices\n```\n\n\u003e We _actually_ recommend that this library gets included in your project\n\u003e using [Strauss](https://github.com/BrianHenryIE/strauss).\n\u003e\n\u003e Luckily, adding Strauss to your `composer.json` is only slightly more complicated than adding a\n\u003e typical dependency, so checkout\n\u003e our [strauss docs](https://github.com/stellarwp/global-docs/blob/main/docs/strauss-setup.md).\n\n## Configuration \u0026 Initialization\n\nThe `AdminNotices` class can be used to configure the library to work within your system and avoid\nconflicts with other plugins. Here's an example of what typical setup may look like:\n\n```php\nuse StellarWP\\AdminNotices\\AdminNotices;\n\nAdminNotices::initialize('my_plugin', plugin_dir_url(__FILE__) . 'vendor/stellarwp/admin-notices');\n```\n\nThe `initialize` method accepts two arguments:\n\n1. A unique identifier for your plugin. This is used to avoid conflicts with other plugins.\n2. The URL to the library's assets directory. This is used to enqueue the necessary JS files.\n\n### Service Containers\n\nIt is not required to use a service container with this library, however if you are using one and\nwant it to fit within your system, you can connect your container, which **must** implement the\n`Psr\\Container\\ContainerInterface` interface.\n\nOnce connected, your container must provide a concrete instance of the\n`StellarWP\\AdminNotices\\Contracts\\NotificationsRegistrarInterface` interface. You can either bind\nthe `StellarWP\\AdminNotices\\NotificationsRegistrar` class to the interface, or create your own class\nthat implements the interface.\n\n```php\n$container-\u003eset('StellarWP\\AdminNotices\\Contracts\\NotificationsRegistrarInterface', function () {\n    return new StellarWP\\AdminNotices\\NotificationsRegistrar();\n});\n\nAdminNotices::setContainer($container);\n```\n\n## Displaying Notices\n\nAll notices are displayed using the `StellarWP\\AdminNotices\\AdminNotices` facade. There are a few\nmethods to manage notices:\n\n### `addNotice($id, $message)`\n\nAdds a notice to the queue to be displayed in the standard WordPress admin notice area.\n\nParameters:\n\n1. `string $id` - A unique identifier for the notice.\n2. `string|callback $message` - The message to display. This can be a string or a callback that\n   returns a string. The callback receives an instance of the `AdminNotice` class and an instance of\n   the [NoticeElementProperties](src/DataTransferObjects/NoticeElementProperties.php) class — the\n   latter of which is useful for custom notices.\n\n```php\nuse StellarWP\\AdminNotices\\AdminNotices;\nuse StellarWP\\AdminNotices\\AdminNotice;\nuse \\StellarWP\\AdminNotices\\DataTransferObjects\\NoticeElementProperties;\n\nAdminNotices::show('my_notice', 'This is a notice');\nAdminNotices::show('my_notice', function (AdminNotice $notice, NoticeElementProperties $elements) {\n    return 'This is a notice';\n});\n```\n\n### `removeNotice($id)`\n\nRemoves a notice from the queue.\n\nParameters:\n\n1. `string $id` - The unique identifier for the notice to remove\n\n```php\nuse StellarWP\\AdminNotices\\AdminNotices;\n\nAdminNotices::removeNotice('my_notice');\n```\n\n### `render(AdminNotice $notice)`\n\nImmediately renders the notice to the screen. This is useful if you want to display the notice in a\nnon-standard location.\n\nParameters:\n\n1. `AdminNotice $notice` - The notice to render\n\n```php\nuse StellarWP\\AdminNotices\\AdminNotices;\n\n$notice = new AdminNotice('my_notice', 'This is a notice');\nAdminNotices::render($notice);\n```\n\n## Notice Conditions\n\nAt the core of this library is the `AdminNotice` class. This class is used to define the notice and\nits conditions. When the `AdminNotices::show()` method is used, it returns a new instance of the\n`AdminNotice` class to be fluently configured. For example:\n\n```php\nuse StellarWP\\AdminNotices\\AdminNotices;\n\n$notice = AdminNotices::show('my_notice', 'This is a notice')\n    -\u003eon('edit.php');\n    -\u003eifUserCan('manage_options')\n    -\u003edismissible()\n```\n\n### `on(...$screen)`\n\nSets the screen where the notice should be displayed. This can be one of:\n\n* A string representing a portion of the URL\n* A regex delimited with ~ to compare against the URL (e.g. `~edit\\.php~i`)\n* An associative array that is compared against the `WP_Screen` object (e.g.\n  `['id' =\u003e 'edit-post']`)\n\nIf multiple screen conditions are provided, the notice will be displayed if any of the conditions\nare met.\n\nParameters:\n\n1. `string|array $screen` - The screen to display the notice on\n\n```php\nuse StellarWP\\AdminNotices\\AdminNotices;\n\n// Display the notice where the URL contains 'edit.php'\n$notice = AdminNotices::show('my_notice', 'This is a notice')\n    -\u003eon('edit.php');\n\n// Display the notice where the URL matches the regex\n$notice = AdminNotices::show('my_notice', 'This is a notice')\n    -\u003eon('~edit\\.php~i');\n\n// Display the notice on the 'edit-post' screen\n$notice = AdminNotices::show('my_notice', 'This is a notice')\n    -\u003eon(['id' =\u003e 'edit-post']);\n```\n\n### `ifUserCan(...$capability)`\n\nSets the capability required to view the notice. This can be a single capability or an array of\ncapabilities. Under the hood, `current_user_can` is used to check the capability. Each capability\ncan be one of:\n\n* A string representing a capability\n* An array where the elements are spread to the `current_user_can` function\n* An instance of the `StellarWP\\AdminNotices\\ValueObjects\\UserCapability` class\n\nIf multiple capabilities are provided, the notice will be displayed if the user has\nany of the capabilities.\n\nParameters:\n\n1. `string|array|UserCapability $capability` - The capability required to view the notice\n\n```php\nuse StellarWP\\AdminNotices\\AdminNotices;\n\n// Display the notice if the user can manage options\n$notice = AdminNotices::show('my_notice', 'This is a notice')\n    -\u003eifUserCan('manage_options');\n\n// Display the notice if the user can manage options or edit posts\n$notice = AdminNotices::show('my_notice', 'This is a notice')\n    -\u003eifUserCan('manage_options', 'edit_posts');\n\n// Display the notice if the user can edit post 1\n$notice = AdminNotices::show('my_notice', 'This is a notice')\n    -\u003eifUserCan(['edit_post', 1]);\n\n// Display the notice via a UserCapability object\n$capability = new StellarWP\\AdminNotices\\ValueObjects\\UserCapability('manage_options');\n$notice = AdminNotices::show('my_notice', 'This is a notice')\n    -\u003eifUserCan($capability);\n```\n\n### `after($date)`\n\nSets the date after which the notice should be displayed.\n\nParameters:\n\n1. `string $date` - The date after which the notice should be displayed.\n\n```php\nuse StellarWP\\AdminNotices\\AdminNotices;\n\n// Display the notice after January 1, 2022, using a date parsable string\n$notice = AdminNotices::show('my_notice', 'This is a notice')\n    -\u003eafter('2022-01-01');\n\n// Display the notice after January 1, 2022, using a DateTime object\n$date = new DateTime('2022-01-01');\n$notice = AdminNotices::show('my_notice', 'This is a notice')\n    -\u003eafter($date);\n\n// Display the notice after January 1, 2022, using a timestamp\n$notice = AdminNotices::show('my_notice', 'This is a notice')\n    -\u003eafter(1640995200);\n```\n\n### `until($date)`\n\nSets the date until which the notice should be displayed.\n\nParameters:\n\n1. `string $date` - The date until which the notice should be displayed.\n\n```php\nuse StellarWP\\AdminNotices\\AdminNotices;\n\n// Display the notice until January 1, 2022, using a date parsable string\n$notice = AdminNotices::show('my_notice', 'This is a notice')\n    -\u003euntil('2022-01-01');\n\n// Display the notice until January 1, 2022, using a DateTime object\n$date = new DateTime('2022-01-01');\n$notice = AdminNotices::show('my_notice', 'This is a notice')\n    -\u003euntil($date);\n\n// Display the notice until January 1, 2022, using a timestamp\n$notice = AdminNotices::show('my_notice', 'This is a notice')\n    -\u003euntil(1640995200);\n```\n\n### `between($start, $end)`\n\nSets the date range during which the notice should be displayed. The dates can be the same string,\nint, or DateTime object as the `after` and `until` methods.\n\nParameters:\n\n1. `string $start` - The start date of the range.\n2. `string $end` - The end date of the range.\n\n```php\nuse StellarWP\\AdminNotices\\AdminNotices;\n\n// Display the notice between January 1, 2022, and January 31, 2022, using date parsable strings\n$notice = AdminNotices::show('my_notice', 'This is a notice')\n    -\u003ebetween('2022-01-01 00:00:00', '2022-01-31 23:59:59');\n```\n\n### `when($callback)`\n\nSets a custom condition for when the notice should be displayed. The callback should return a\nboolean value.\n\nParameters:\n\n1. `callable $callback` - The callback that returns a boolean value\n\n```php\nuse StellarWP\\AdminNotices\\AdminNotices;\n\n// Display the notice if the current user is an administrator\n$notice = AdminNotices::show('my_notice', 'This is a notice')\n    -\u003ewhen(function () {\n        $user = wp_get_current_user();\n        return in_array('administrator', $user-\u003eroles);\n    });\n```\n\n## Standard Notice Visual \u0026 behavior options\n\n### `autoParagraph($autoParagraph)`, `withoutAutoParagraph()`\n\n**Default:** false\n\nSets whether the notice message should be automatically wrapped in a paragraph tag. It uses wpautop\nunder the hood.\n\nParameters:\n\n1. `bool $autoParagraph = true` - Whether to automatically wrap the message in a paragraph tag\n\n```php\nuse StellarWP\\AdminNotices\\AdminNotices;\n\n// Automatically wrap the message in a paragraph tag\n$notice = AdminNotices::show('my_notice', 'This is a notice')\n    -\u003eautoParagraph();\n\n// Do not automatically wrap the message in a paragraph tag\n$notice = AdminNotices::show('my_notice', 'This is a notice')\n    -\u003eautoParagraph(false);\n\n// Also has an alias for readability\n$notice = AdminNotices::show('my_notice', 'This is a notice')\n    -\u003ewithoutAutoParagraph();\n```\n\n### `urgency($urgency)`\n\n**Default:** 'info'\n\nSets the urgency of the notice. This is used to determine the color of the notice. **Only works when\nthe wrapper is enabled.**\n\nParameters:\n\n1. `string $urgency` - The urgency of the notice. Can be 'info', 'success', 'warning', or 'error'\n\n```php\nuse StellarWP\\AdminNotices\\AdminNotices;\n\n// Set the notice urgency to 'success'\n$notice = AdminNotices::show('my_notice', 'This is a notice')\n    -\u003eurgency('success');\n\n// The StellarWP\\AdminNotices\\ValueObjects\\Urgency class can also be used\n$urgency = new StellarWP\\AdminNotices\\ValueObjects\\Urgency('success');\n$notice = AdminNotices::show('my_notice', 'This is a notice')\n    -\u003eurgency($urgency);\n```\n\n### `alternateStyles($useAlternate)`, `standardStyles()`\n\n**Default:** false\n\nSets whether the notice should use the alternate WordPress notice styles. **Only works when the\nwrapper is enabled.**\n\nParameters:\n\n1. `bool $useAlternate = true` - Whether the notice should use the alternate WordPress notice\n   styles\n\n```php\nuse StellarWP\\AdminNotices\\AdminNotices;\n\n// Use the alternate WordPress notice styles\n$notice = AdminNotices::show('my_notice', 'This is a notice')\n    -\u003ealternateStyles();\n\n// Use the standard WordPress notice styles, only necessary to revert back\n$notice = AdminNotices::show('my_notice', 'This is a notice')\n    -\u003ealternateStyles()\n    -\u003estandardStyles();\n```\n\n### `inline($inline)`, `notInline()`\n\n**Default:** false\n\nSets whether the notice should be displayed in the WP \"inline\" location, at the top of the admin\npage. **Only works when the wrapper is enabled.**\n\nParameters:\n\n1. `bool $inline = true` - Whether the notice should be displayed inline\n\n```php\nuse StellarWP\\AdminNotices\\AdminNotices;\n\n// Display the notice inline\n$notice = AdminNotices::show('my_notice', 'This is a notice')\n    -\u003einline();\n\n// Display the notice in the standard location\n$notice = AdminNotices::show('my_notice', 'This is a notice')\n    -\u003einline(false);\n\n// Also has an alias for readability\n$notice = AdminNotices::show('my_notice', 'This is a notice')\n    -\u003enotInline();\n```\n\n### `dismissible($dismissible)`, `notDismissible()`\n\n**Default:** false\n\nSets whether the notice should be dismissible. This adds a dismiss button to the notice. When the\nuser dismisses the notice, it is permanently dismissed. This is stored in the user's preference\nmeta. **Only works when the wrapper is enabled.**\n\nParameters:\n\n1. `bool $dismissible = true` - Whether the notice should be dismissible\n\n```php\nuse StellarWP\\AdminNotices\\AdminNotices;\n\n// Make the notice dismissible\n$notice = AdminNotices::show('my_notice', 'This is a notice')\n    -\u003edismissible();\n\n// Make the notice not dismissible\n$notice = AdminNotices::show('my_notice', 'This is a notice')\n    -\u003edismissible(false);\n\n// Also has an alias for readability\n$notice = AdminNotices::show('my_notice', 'This is a notice')\n    -\u003enotDismissible();\n```\n\n## Custom Notices\n\nSometimes you want to display a notice, but you want to completely style it yourself. This is\npossible and pretty straightforward to do.\n\nStart by using the `custom` method on the notice. This will disable all standard visual and behavior\n\n```php\nuse StellarWP\\AdminNotices\\AdminNotices;\n\n$notice = AdminNotices::show('my_notice_custom', 'This is a notice')\n    -\u003ecustom();\n```\n\n### `location()`\n\n***Default:*** 'standard'\n\nSets the location in one of the standard WordPress notice locations. By default, the notice will be\ndisplayed in the standard location.\n\nParameters:\n\n1. `string $location` - The location to display the notice. Can be 'standard', 'above_header', '\n   below_header', or 'inline'. Note that 'standard' and 'below_header' are the same location.\n\n```php\nuse StellarWP\\AdminNotices\\AdminNotices;\n\n// Display the notice above the header\n$notice = AdminNotices::show('my_notice_custom', 'This is a notice')\n    -\u003ecustom()\n    -\u003elocation('above_header');\n```\n\n### Dismissing\n\nThe `dismissible` method is not available for custom notices. If you want to add a dismiss button,\nyou will need to do so manually. Fortunately, there is a simple way to do this.\n\n```php\nuse StellarWP\\AdminNotices\\AdminNotices;\nuse StellarWP\\AdminNotices\\AdminNotice;\nuse \\StellarWP\\AdminNotices\\DataTransferObjects\\NoticeElementProperties;\n\n$renderCallback = function (AdminNotice $notice, NoticeElementProperties $elements) {\n    return \"\n        \u003cdiv\u003e\n            \u003cp\u003eThis is a custom notice\u003c/p\u003e\n            \u003cbutton type='button' {$elements-\u003ecloseAttributes()}\u003e\n                \u003cspan class='screen-reader-text'\u003eDismiss this notice.\u003c/span\u003e\n            \u003c/button\u003e\n        \u003c/div\u003e\n    \";\n};\n\nAdminNotices::show('my_notice', $renderCallback)\n    -\u003ecustom();\n```\n\nThe [$elements](src/DataTransferObjects/NoticeElementProperties.php) object provides a\n`customCloserAttributes` method that returns the necessary attributes to be place on the dismiss\nbutton. This method will add the necessary attributes to dismiss the notice when clicked. This will\npermanently dismiss the notice, and fade out the notice, similar to the standard WordPress\ndismissible notices.\n\nIf you want the notice to be marked as dismissed, but not fade out, you can pass \"clear\" to the\n`customerCloserAttributes` method: e.g. `$elements-\u003ecustomCloserAttributes('clear')`.\n\n## Custom scripts \u0026 styles\n\nOften times, especially for custom notices, you may want to enqueue custom scripts and styles,\nhowever they should only be enqueued when the notice is displayed. This can be done by using the\n`enqueueScript` and `enqueueStyle` methods on the notice.\n\n### `enqueueScript($src, $deps = [], $ver = false, $args = [])`\n\nEnqueues a script to be loaded when the notice is displayed, following the same parameters as\n`wp_enqueue_script`. The only difference is that the loading strategy is \"defer\" by default.\n\n```php\nuse StellarWP\\AdminNotices\\AdminNotices;\n\n$notice = AdminNotices::show('my_notice', 'This is a notice')\n    -\u003eenqueueScript('https://example.com/my-script.js', ['jquery']);\n```\n\n### `enqueueStyle($src, $deps = [], $ver = false, $media = 'all')`\n\nEnqueues a style to be loaded when the notice is displayed, following the same parameters as\n`wp_enqueue_style`.\n\n```php\nuse StellarWP\\AdminNotices\\AdminNotices;\n\n$notice = AdminNotices::show('my_notice', 'This is a notice')\n    -\u003eenqueueStylesheet('https://example.com/my-style.css');\n```\n\n## Resetting dismissed notices\n\nFor dismissible notices, when the user dismisses the notice, it is permanently dismissed. If you\nwant\nto reset the dismissed notice(s), there are a couple methods available.\n\n### `resetNoticeForUser($notificationId, $userId)`\n\nReset a specific notification for a user.\n\nParameters:\n\n1. `string $notificationId` - The unique identifier for the notice\n2. `int $userId` - The user ID to reset the notice for\n\n```php\nuse StellarWP\\AdminNotices\\AdminNotices;\n\nAdminNotices::resetNoticeForUser('my_notice', get_current_user_id());\n```\n\n### `resetAllNoticesForUser($userId)`\n\nReset all dismissed notices for a user.\n\nParameters:\n\n1. `int $userId` - The user ID to reset all notices for\n\n```php\nuse StellarWP\\AdminNotices\\AdminNotices;\n\nAdminNotices::resetAllNoticesForUser(get_current_user_id());\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstellarwp%2Fadmin-notices","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstellarwp%2Fadmin-notices","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstellarwp%2Fadmin-notices/lists"}