typisttech / wp-admin-notices
A simplified OOP implementation of the WordPress admin notices
Fund package maintenance!
tangrufus
typist.tech/donation
www.paypal.me/iAmTangRufus/30usd
Installs: 1 040
Dependents: 0
Suggesters: 0
Security: 0
Stars: 15
Watchers: 3
Forks: 0
Open Issues: 2
Requires
- php: >7.0
Requires (Dev)
- codeception/aspect-mock: ^2.0
- jakoch/phantomjs-installer: ^2.1
- lucatume/wp-browser: ^1.21
- neronmoon/scriptsdev: ^0.1.1
- site5/phantoman: ^2.0
- wp-coding-standards/wpcs: ^0.13.1
Suggests
- typisttech/imposter-plugin: Wrap all composer vendor packages inside your own namespace, to prevent collisions when multiple plugins use this library
- typisttech/wp-contained-hook: Lazily instantiate objects from dependency injection container to WordPress hooks (actions and filters)
This package is auto-updated.
Last update: 2024-11-05 09:53:15 UTC
README
A simplified OOP implementation of the WordPress admin notices.
- The Goals, or What This Package Does?
- Install
- Usage
- Frequently Asked Questions
- Can I implement my own notice classes?
- Can I use a different storage scheme other than
wp_option
table? - Is this a plugin?
- What to do when wp.org plugin team tell me to clean up the
vendor
folder? - Can two different plugins use this package at the same time?
- Do you have a demo plugin that use this package?
- Do you have real life examples that use this package?
- It looks awesome. Where can I find some more goodies like this?
- Support
- Developing
- Running the Tests
- Feedback
- Change log
- Security
- Contributing
- Credits
- License
The Goals, or What This Package Does?
Install
Installation should be done via composer, details of how to install composer can be found at https://getcomposer.org/.
$ composer require typisttech/wp-admin-notices
You should put all WP Admin Notices
classes under your own namespace to avoid class name conflicts.
Usage
Example
use TypistTech\WPAdminNotices\Factory; use TypistTech\WPAdminNotices\Notice; use TypistTech\WPAdminNotices\StickyNotice; $store = Factory::build('my_unique_demo_option', 'my_unique_demo_action'); add_action('admin_init', function () use ($store) { $notice = new Notice('example-notice-1', 'my notice message'); $store->add($notice); } ); add_action('post_updated', function ($post_id) use ($store) { $notices[] = new Notice( 'example-notice-2', "<p><strong>WPAdminNotices</strong>: Post ID: $post_id has been updated.</p>", Notice::SUCCESS ); $notices[] = new StickyNotice( 'example-notice-3', '<p><strong>WPAdminNotices</strong>: StickyNotice persists in database until user clicks to dismiss it.</p>' ); $store->add(...$notices); } );
Notice
One-off notice that guaranteed to be shown once and once only.
__construct(string $handle, string $content, string $type = null)
Notice
constructor.
- @param string $handle The notice's unique identifier.
- @param string $content The HTML content of the notice.
- @param string|null $type The notice's type. Expecting one of
Notice::UPDATE_NAG
,Notice::ERROR
,Notice::WARNING
,Notice::INFO
,Notice::SUCCESS
. Default isNotice::INFO
.
Notice::UPDATE_NAG
is not suitable for regular admin notices. See WordPress codex.
$notice = new Notice('example-notice', '<strong>Hello</strong> World!', Notice::SUCCESS);
StickyNotice
StickyNotice
persists in database until user clicks to dismiss it.
__construct(string $handle, string $content, string $type = null)
StickyNotice
constructor.
- @param string $handle The notice's unique identifier. Also used to permanently dismiss a sticky notice.
- @param string $content The HTML content of the notice.
- @param string|null $type The notice's type. Expecting one of
StickyNotice::ERROR
,StickyNotice::WARNING
,StickyNotice::INFO
,StickyNotice::SUCCESS
. Default isStickyNotice::INFO
.
UPDATE_NAG
is not available for StickyNotice
.
$stickyNotice = new StickyNotice('example-sticky-notice', 'I wont go away until users click on me.', StickyNotice::WARNING);
Store
By default, WP Admin Notices
stores notices in WordPress' wp_option
table via Store
.
If you want to use an alternative store, see FAQ.
__construct(string $optionKey)
Store
constructor.
- @param string $optionKey Key in options table that holds all enqueued notices.
$store = new Store('my_unique_option_key');
add(NoticeInterface ...$notices)
Enqueue admin notices to database.
Not limited to Notice
and StickyNotice
only, any instance of NoticeInterface
is accepted. See FAQ.
- @param NoticeInterface[] ...$notices Notices to be enqueued.
$store->add($notice1, $notice2); // To update a notice, re-add with the same handle. $oldNotice = new Notice('i-am-unique', "Chaos isn't a pit."); $store->add($oldNotice); $newNotice = new Notice('i-am-unique', 'Chaos is a ladder.'); $store->add($newNotice);
delete(string $handle)
Delete an enqueued notice.
- @param string $handle Handle of the notice to be deleted.
$store->delete('i-am-unique');
Notifier
Notifier
handles all interactions between WordPress and this package via action hooks. You have to hook it into WordPress via add_action
unless you use Factory
.
__construct(string $action, StoreInterface $store)
Notifier constructor.
- @param string $action AJAX request's 'action' property for sticky notices.
- @param StoreInterface $store Connector to notice storage.
$store = new Store('my_unique_option_key'); $notifier = new Notifier('my_unique_action', $store); add_action('admin_notices', [$notifier, 'renderNotices']); add_action("wp_ajax_my_unique_action", [$notifier, 'dismissNotice']); add_action('admin_footer', [$notifier, 'renderScript']);
Factory
Factory
is a helper class to reduce boilerplate code for those who use default Store
class. If you use a custom store, don't use this class.
build(string $optionKey, string $action): Store
- @param string $optionKey Key in options table that holds all enqueued notices.
- @param string $action AJAX request's 'action' property for sticky notices.
- @return Store
$store = Factory::build('my_unique_option_key', 'my_unique_action');
Frequently Asked Questions
Can I implement my own notice classes?
Of course! Just implements the NoticeInterface
.
Take a look at classes Notice
and StickyNotice
as well as their tests for example implementations of StoreInterface
.
If you'd like to create a open-source package to do this to help others, open a new issue to let us know, we'd love to help you with it.
Can I use a different storage scheme other than wp_option
table?
Of course! WP Admin Notices
data store is completely swappable, and always has been.
To implement a custom store:
- Implement
StoreInterface
- Pass you custom store to
Notifier
class MyCustomStore implements StoreInterface { // Implements all the required methods. } $store = new MyCustomStore; $action = 'my_unique_action'; $notifier = new Notifier($action, $store); add_action('admin_notices', [$notifier, 'renderNotices']); add_action("wp_ajax_$action", [$notifier, 'dismissNotice']); add_action('admin_footer', [$notifier, 'renderScript']);
Take a look at the Store
class and StoreTest
for an example implementation of StoreInterface
.
If you'd like to create a open-source package to do this to help others, open a new issue to let us know, we'd love to help you with it.
Is this a plugin?
No, this is a package that should be part of your plugin.
What to do when wp.org plugin team tell me to clean up the vendor
folder?
Re-install packages via the following command. This package exports only necessary files to dist
.
$ composer install --no-dev --prefer-dist --optimize-autoloader
Can two different plugins use this package at the same time?
Yes, if put all WP Admin Notices
classes under your own namespace to avoid class name conflicts.
Do you have a demo plugin that use this package?
You can install this demo plugin by
$ wp plugin install https://github.com/TypistTech/wp-admin-notices/archive/nightly.zip --activate
Check out wp-admin-notices.php
. We use it for acceptance tests.
Do you have real life examples that use this package?
Here you go:
Add your own plugin here
It looks awesome. Where can I find some more goodies like this?
- Articles on Typist Tech's blog
- Tang Rufus' WordPress plugins on wp.org
- More projects on Typist Tech's GitHub profile
- Stay tuned on Typist Tech's newsletter
- Follow Tang Rufus' Twitter account
- Hire Tang Rufus to build your next awesome site
Support
Love wp-admin-notices
? Help me maintain it, a donation here can help with it.
Why don't you hire me?
Ready to take freelance WordPress jobs. Contact me via the contact form here or, via email info@typist.tech
Want to help in other way? Want to be a sponsor?
Contact: Tang Rufus
Developing
To setup a developer workable version you should run these commands:
$ composer create-project --keep-vcs --no-install typisttech/wp-admin-notices:dev-master
$ cd wp-admin-notices
$ composer install
Running the Tests
WP Admin Notices run tests on Codeception and relies wp-browser to provide WordPress integration. Before testing, you have to install WordPress locally and add a codeception.yml file. See *.suite.example.yml for Local by Flywheel configuration examples.
Actually run the tests:
$ composer test
We also test all PHP files against PSR-2: Coding Style Guide and part of the WordPress coding standard.
Check the code style with $ composer check-style
.
Feedback
Please provide feedback! We want to make this package useful in as many projects as possible. Please submit an issue and point out what you do and don't like, or fork the project and make suggestions. No issue is too small.
Change log
Please see CHANGELOG for more information on what has changed recently.
Security
If you discover any security related issues, please email wp-admin-notices@typist.tech instead of using the issue tracker.
Contributing
Please see CONTRIBUTING and CODE_OF_CONDUCT for details.
Credits
WP Admin Notices is a Typist Tech project and maintained by Tang Rufus, freelance developer for hire.
Full list of contributors can be found here.
License
WP Admin Notices is licensed under the GPLv2 (or later) from the Free Software Foundation. Please see License File for more information.