1. Add mediaButtons: true to the setting object that you pass to the function:

wp.editor.initialize('textarea-id', {
	tinymce: { /* ... */ },
	quicktags: true,
	mediaButtons: true // <---
});

2. Call wp_enqueue_media() somewhere, like from the admin_enqueue_scripts hook.

This should make the “Add Media” button appear above the editor.

Why?

When I’m writing a plugin, I sometimes need to know not just what a hook does, but also when it runs in relation to other hooks. The official WordPress documentation has a list of common actions, but it’s out of date and far from complete. There have been other attempts to document the hook execution order, but those are also a few years old now and not comprehensive.

This is not entirely surprising. WordPress comes with hundreds of unique actions and filters, and some of them are called dozens of times per page. Manually collating and maintaining an ordered list of all hooks would require a huge amount of work. Fortunately, it’s possible to automate some of that work, which is what I’ve done for this project.

What is it?

HookOrder.com is a documentation/reference site that shows the execution order of all unique WordPress hooks that are fired on common pages. Notable features include:

• Up to date with WordPress 6.1 (as of this writing).
• Shows both actions and filters. You can hide filters if you’re only interested in actions.
• Hook documentation in the sidebar.
• Shows active callbacks, if any.
• Shows hook arguments. The actual values will be different on each site, of course, but it can be handy to see some practical examples.

How does it work?

The hook lists are generated by setting up a basic WordPress site and logging every do_action(), apply_filters(), etc call that happens during a request.  A bunch of post-processing is necessary to normalize and format the results and make the database fast enough to be usable.

For anyone curious, here are some of the tools I used:

• The all hook makes it possible to catch every action and filter. The hook itself appears to be undocumented, but see _wp_call_all_hook.
• Puppeteer – to control headless Chrome.
• WP-CLI – to install and configure WordPress, activate plugins, create or import sample data, and so on.
• Theme Test Data – to fill out the site and hopefully make the results more realistic.
• SQLite – for temporary log storage.
• Hook documentation parser – to extract hook documentation from WordPress source code.
• Miscellaneous Symfony Components.

In this post I’ll try to answer that question in the context of using WP Update Server to serve plugin updates. I will also provide a couple of practical examples from one of my commercial plugins.

Lets get started. There are many ways to secure update downloads, but most of them boil down to this:

1. Give some kind of security token to each user. This could be a login + password to a membership site, a license key, or something more esoteric.
2. Whenever someone installs your plugin on their site, ask them to enter the key/log in/whatever.
3. Modify the plugin to append the token to each update request.
4. Write a server script that verifies the token before it allows download.

Choose a Security Token

How you implement the first two steps will vary greatly depending on your plugin UI and what online store, cart software, or membership plugin you use. You might already have some kind of customer authentication mechanism in place that just needs a bit of tweaking to be used for updates, or you might need to build your own from scratch. There’s no “one size fits all” solution here.

Personally, I prefer to use license keys. Whenever someone buys my Admin Menu Editor Pro plugin, the order processing script generates a random key, stores it in the database, and sends the key and a download link to the customer’s email. Then, when they install the plugin, there’s a link to enter the license key.

I won’t include the license management code here because it’s beyond the scope of this post and built for that specific plugin, but the user interface looks something like this (click to enlarge):

Add the Token To Update Requests

Now, how do we add our security token to each update request? You can do that by using the addQueryArgFilter($callback) method of the update checker. The callback function will receive an associative array of query arguments. Just add the token to the list and return the modified array.

Here’s an example:

/* ... Code that initializes the update checker ... */

//Add the license key to query arguments.
$updateChecker->addQueryArgFilter('wsh_filter_update_checks');
function wsh_filter_update_checks($queryArgs) {
	$settings = get_option('my_plugin_settings');
	if ( !empty($settings['license_key']) ) {
		$queryArgs['license_key'] = $settings['license_key'];
	}
	return $queryArgs;
}

Use the Token To Authorize Downloads

Finally, let’s make the update server verify the security token before it lets the user download an update. To do that, you’ll need to create a custom server class (see Extending the server) and override at least the Wpup_UpdateServer::checkAuthorization($request) method. Here’s what you should do in this method:

1. Retrieve the query argument(s) that contains the token by using $request->param('arg_name').
2. Verify the token. Again, this part is up to you. You could look it up in a database, use a checksum to validate it, or something else.
3. If the token is good, you don’t need to do anything special.
4. If the token is invalid, call $this->exitWithError('Error message') to output an error and stop script execution.

Below is a simplified version of the script I use to implement secure updates for  Admin Menu Editor Pro. It is slightly more advanced than the above outline, but the general idea is the same.

(Again, license management is beyond the scope of this post, so I’ve omitted most of the code that deals with loading and validating licenses. Just treat verifyLicenseExists() and other licensing functions as pseudo-code.)

class SecureUpdateServer extends Wpup_UpdateServer {
	protected $licenseServer;

	public function __construct($serverUrl, $licenseServer) {
		parent::__construct($serverUrl);
		$this->licenseServer = $licenseServer;
	}

	protected function initRequest($query = null, $headers = null) {
		$request = parent::initRequest($query, $headers);

		//Load the license, if any.
		$license = null;
		if ( $request->param('license_key') ) {
			$result = $this->licenseServer->verifyLicenseExists(
				$request->slug,
				$request->param('license_key')
			);
			if ( is_wp_error($result) ) {
				//If the license doesn't exist, we'll output an invalid dummy license.
				$license = new Wslm_ProductLicense(array(
					'status' => $result->get_error_code(),
					'error' => array(
						'code' => $result->get_error_code(),
						'message' => $result->get_error_message(),
					),
				));
			} else {
				$license = $result;
			}
		}

		$request->license = $license;
		return $request;
	}

	protected function filterMetadata($meta, $request) {
		$meta = parent::filterMetadata($meta, $request);

		//Include license information in the update metadata. This saves an HTTP request
		//or two since the plugin doesn't need to explicitly fetch license details.
		$license = $request->license;
		if ( $license !== null ) {
			$meta['license'] = $this->licenseServer->prepareLicenseForOutput($license);
		}

		//Only include the download URL if the license is valid.
		if ( $license && $license->isValid() ) {
			//Append the license key or to the download URL.
			$args = array( 'license_key' => $request->param('license_key') );
			$meta['download_url'] = self::addQueryArg($args, $meta['download_url']);
		} else {
			//No license = no download link.
			unset($meta['download_url']);
		}

		return $meta;
	}

	protected function checkAuthorization($request) {
		parent::checkAuthorization($request);

		//Prevent download if the user doesn't have a valid license.
		$license = $request->license;
		if ( $request->action === 'download' && ! ($license && $license->isValid()) ) {
			if ( !isset($license) ) {
				$message = 'You must provide a license key to download this plugin.';
			} else {
				$error = $license->get('error');
				$message = isset($error) ? $error : 'Sorry, your license is not valid.';
			}
			$this->exitWithError($message, 403);
		}
	}
}

If you have any questions, feel free to leave a comment.

Features

• Provide updates for private or commercial plugins and themes.
  From the users’ perspective, the updates work just like they do with plugins and themes listed in the official WordPress.org directory.
  
• Easy to set up.
  Just upload the script to your site and drop a plugin or theme Zip in the “packages” subdirectory.
• Easy to integrate with existing plugins and themes.
  All it takes is about 5 lines of code.
• Minimal server requirements.
  The server component requires PHP 5.3+ and the Zip extension. The update checker component only requires PHP 5.2 – same as the current version of WordPress.
• Extensible.
  Want to secure your upgrade download links? Or use a custom logger or cache? Maybe you ‘d like to load the change log and other update meta from the database instead of parsing it from a Zip file? Create your own, customized update server by extending the Wpup_UpdateServer class.

What’s Next?

See the GitHub repository for download links and usage instructions. The documentation still needs work, but it should be good enough to get you up and running.

It also tracks how long each plugin has been active on your site and automatically reports plugins that have been active for a while (1 week by default) as compatible – unless, of course, you’ve already marked them as broken. This way you won’t need to waste time on reporting that some plugins work fine.

See also: Why use this plugin?

Screenshots

Plugin settings page

You can use these “works” and “broken” links to report if a plugin is working properly with your WP version

Download

• Download plugin
• GitHub repository

Requires WordPress 3.4 or later.

Installation

1. Go to Plugins -> Add New -> Upload and upload the plugin archive to your site.
2. Activate the plugin via the “Plugins” page.
3. Go to Plugins -> Compatibility Reporter and enter your WordPress.org credentials in the appropriate fields. If you don’t have a WordPress.org account yet, you can get one here.
4. (Optional) Change how long a plugin needs to be active before it gets marked as working. The default is 1 week.
5. The plugin will now download your existing compatibility votes. This happens in the background and can take up to 10 minutes.
6. You should see “Works” and “Broken” links on your “Plugins” page. Click them to report your plugins as compatible or incompatible with your WordPress version. Your current vote (if any) will be displayed in bold.

Why Use It?

The main goal of this plugin is to make the compatibility reports that WordPress.org displays for each plugin more useful. Right now, most plugins only have a handful of votes – not enough to reliably determine if they’re compatible with this or that WordPress version.

Exhibit A

Even plugins that have been downloaded millions of times usually have only a couple dozen of compatibility reports for the current version, at best. Why is that, and how does this plugin help the situation?

1. Reporting plugin compatibility is inconvenient.

To be able to vote, you first have to sign up for a WordPress.org account. That’s easy enough and you only need to do it once. Then, when you actually want to report a plugin as working or broken, you need to:

1. Go to WordPress.org.
2. Remember your username and password.
3. Find the plugin you want to vote on. There might be a “Visit plugin homepage” link on the “Plugins” page, but that usually leads to the author’s site, not the WordPress.org listing.
4. Find your plugin version in the drop-down list.
5. Find your WordPress version in the second list.
6. Click “Works” or “Broken”.

Multiply this by the number of plugins you have installed and the number of plugin and WordPress updates, and you’ll see why most people don’t bother with it. This plugin simplifies the process down to clicking a “Works” or “Broken” link on your “Plugins” page. You only have to enter your WordPress.org account details once: when setting up the plugin.

2.There’s little incentive to mark plugins as working.

Of those users who do send compatibility reports, many do it only when a plugin doesn’t work. Even if you deliberately try to avoid this and always report compatible plugins as working, it can get tiresome quickly since new plugin versions are released all the time.

One side-effect of this is that compatibility figures tend to be unfairly biased towards “broken”. For example, take Jetpack which currently has 29 “works” and 8 “broken” votes. I seriously doubt that a plugin that was made by the same folk who run WordPress.com is broken on 8/37 = 22% of sites.

Plugin Compatibility Reporter solves this by automatically marking plugins that have been active for a long time as working. This is based on the assumption that the user wouldn’t leave a plugin active if it was incompatible with their site. Of course, you can always change your vote to “broken” if it turns out that the plugin had a subtle bug that you didn’t notice at first.  This plugin will not overwrite your existing reports.

Benefits

• Users get a better idea of how well any given plugin works with the latest version of WordPress.
• Developers get a more accurate impression of what fraction of users are having problems with their plugin.
• Less time is wasted on reporting plugins that work properly.

To make this possible, you’ll need a way to set the post category via the URL. The following snippet lets you do just that. Simply append a category_id=123 parameter to the post editor URL, and it will automatically select the specified category in the “Categories” widget.

Place this code in your functions.php or a functionality plugin:

function ws_preselect_post_category() {
	if ( isset($_GET['category_id']) && is_numeric($_GET['category_id']) ) {
		$catId = intval($_GET['category_id']);
		?>
		<script type="text/javascript">
			jQuery(function() {
				var catId = <?php echo json_encode($catId); ?>;
				jQuery('#in-category-' + catId).click();
			});
		</script>
		<?php
	}
}
add_action('admin_footer-post-new.php', 'ws_preselect_post_category');

Now you can pass in the category ID like this: /wp-admin/post-new.php?category_id=123.

For example, suppose you have a web development blog that has a “JavaScript” category with the ID = 15. You could use this snippet to add a Posts -> Add New JS Article link to the admin menu. When you click it, the “JavaScript” category will be selected automatically:

function ws_add_new_post_link() {
	add_posts_page(
		'Add New JS Article',
		'Add New JS Article',
		'edit_posts',
		'post-new.php?category_id=15'
	);
}
add_action('admin_menu', 'ws_add_new_post_link');

Even if you disable magic quotes in php.ini, WordPress will apply them to $_GET, $_POST, $_COOKIE and other superglobals anyway. If you ever notice unexpected slashes showing up in your input data, this is why.

The function that enables magic quotes is called wp_magic_quotes(). It is declared in /wp-includes/load.php and called in /wp-settings.php, shortly after WordPress finishes loading plugins.

/**
 * Add magic quotes to $_GET, $_POST, $_COOKIE, and $_SERVER.
 *
 * Also forces $_REQUEST to be $_GET + $_POST. If $_SERVER, $_COOKIE,
 * or $_ENV are needed, use those superglobals directly.
 *
 * @access private
 * @since 3.0.0
 */
function wp_magic_quotes() {
	// If already slashed, strip.
	if ( get_magic_quotes_gpc() ) {
		$_GET    = stripslashes_deep( $_GET    );
		$_POST   = stripslashes_deep( $_POST   );
		$_COOKIE = stripslashes_deep( $_COOKIE );
	}

	// Escape with wpdb.
	$_GET    = add_magic_quotes( $_GET    );
	$_POST   = add_magic_quotes( $_POST   );
	$_COOKIE = add_magic_quotes( $_COOKIE );
	$_SERVER = add_magic_quotes( $_SERVER );

	// Force REQUEST to be GET + POST.
	$_REQUEST = array_merge( $_GET, $_POST );
}

So how do you access the clean, un-escaped data?  Unfortunately, it is not possible to completely turn off WordPress magic quotes without editing core files. However, since WordPress adds magic quotes after all plugins have been loaded, you can simply grab the unmodified variables while your plugin is loading (or in the “plugins_loaded” action) and store a local copy for your own use. Here’s an example:

class MyExamplePlugin {
	//Local copies of the PHP superglobals.
	private $get;
	private $post;
	private $cookie;

	public function __construct() {
		/* ... Other plugin code ... */

		add_action('plugins_loaded', array($this, 'captureRequestVars'));
	}

	public function captureRequestVars() {
		//Store the original GET and POST data + cookies.
		$this->get = $_GET;
		$this->post = $_POST;
		$this->cookie = $_COOKIE;

		//If magic quotes are actually enabled in PHP,
		//we'll need to remove the slashes.
		if ( get_magic_quotes_gpc() ) {
			$this->get    = stripslashes_deep($this->get);
			$this->post   = stripslashes_deep($this->post);
			$this->cookie = stripslashes_deep($this->cookie);
		}
	}

	public function doSomethingWithInput() {
		/* ... */

		//Use the internal copy of $_GET.
		$something = $this->get['something'];

		/* ... */
	}
}

$myExamplePlugin = new MyExamplePlugin();

Now you might be wondering: why go to all this trouble with copying built-in PHP variables when you could continue using them as normal and just run stripslashes() on any input data? There are several reasons:

• Sooner or later, you’re going to forget to call stripslashes()somewhere. This can lead to hard-to-find bugs.
• Code duplication. Why spread the backslash-stripping code through-out your entire codebase when you could put it in one place?
• Forward compatibility. If the WordPress team ever decides to stop emulating this deprecated PHP misfeature, plugins and themes that indiscriminately apply stripslashes() to all input data will suddenly break.

That said, I wouldn’t count on WordPress dropping this “feature” any time soon. It’s a matter of backwards compatibility, and sometimes it seems WordPress considers compatibility more important than encouraging good programming practices.

JSONLint is an online JSON validator and formatter. It will check your JSON for syntax errors and format it with proper indentation and line breaks to make it more human-readable (this can be very handy when analysing complex JSON documents). You can either paste your JSON data in the form or enter a URL and have JSONLint fetch it automatically.

Online JSON Editor

There’s a whole bunch of different JSON editors available, but JsonEditorOnline.org is easily the best one I’ve seen. It displays JSON as a hierarchical tree and lets you add, remove and duplicate fields, re-arrange them via drag & drop, change field type, and so on. The interface is intuitive and well thought out.

JSON Browser Add-ons

When you open a JSON document in the browser, most browsers will either offer to download the file or display it as plain text. To make working with JSON more convenient, you can install a JSON viewer add-on that will display JSON documents with syntax highlighting and proper indentation:

• JSONView for Firefox
• JSONView for Chrome
• JSONViewer for Opera

JSONH – Compress JSON

JSONH (“JSON Homogeneous Collections Compressor”) is a way to compress JSON documents that contain multiple items with the same keys. For example, it can take an array like this:

[{"a":"A","b":"B"}, {"a":"C","b":"D"}, {"a":"E","b":"F"}]

and pack it into this:

[2,"a","b","A","B","C","D","E","F"]

then unpack it into the original collection later.

Using compression saves bandwidth and can improve the performance of applications that download or send large amounts of JSON data. JSONH libraries are available for JavaScript, PHP, Python and Ruby.

JSON Schema – Document And Validate JSON

Have you ever wished JSON was more like XML? Probably not. But if you have – JSON Schema is for you. It lets you define the structure of your JSON document, specify validation rules, documentation, references (hyperlinks) and so on. Given a JSON document with a schema, you can then use a JSON validator like JSV to validate it. See also: JSON Schema validator for PHP.

JSONSelect – CSS-like Selectors For JSON

JSONSelect is a powerful CSS-like selector language for JSON documents. You can use it to extract information from complex JSON structures without having to explicitly navigate the object hierarchy. Here are a few example selectors to whet your appetite:

• .foo .bar – select all nodes with the key bar that have an ancestor with the key foo.
• .foo :last-child – select the last child node of the foo object.
• :has(.lang:val("Spanish")) > .level – select the level node of all objects that contain a lang field with the value “Spanish”.
• More examples are available on the project homepage.

jLinq – Query JSON

jLinq is a JavaScript library that lets you run complex queries on JSON arrays. It provides a fluent interface (like jQuery) that you can use to filter your data, extract the fields you need and sort the results. jLinq does have one drawback: the library hasn’t been updated in a while, and might no longer be maintained.

Underscore-CLI – Manipulate JSON On The Command-line

Underscore-CLI is the swiss-army knife of JSON processing. This command-line tool can do anything from basic pretty-printing to running arbitrary JavaScript or CoffeeScript. You can filter JSON documents, extract specific properties, apply arbitrary transformations to values (map/reduce/reduceRight), fill in missing properties with defaults, and much, much more. Underscore-CLI also supports the JSONSelect selector syntax mentioned above.

For those of you not familiar with this library, here’s a short summary:

• You can use it to add automatic update support to any WordPress plugin.
• Especially useful for commercial plugins that can’t be hosted on the official WordPress.org repository.
• Free and open source.
• See the original post for more details.

Here’s what’s new in this version:

Added a “Check For Updates” Link

This version adds a new “Check for updates” link to the associated plugin’s row in the Plugins page. Clicking the link will trigger an immediate update check. You can change the link text by using the puc_manual_check_link-$slug filter. To disable the link, return an empty string from the filter.

Debug Bar Integration

(Click to view full size screenshot.) 

Judging by the comments that the previous version received, one of the things that it was really missing was better error reporting and debugging features. When it worked, it worked well. When it didn’t, it was ridiculously hard to figure out why.

To make debugging easier, this version adds a new Debug Bar panel that displays all kinds of useful information about the update checker, including all of its configuration fields, last check timestamp, cached update information and more. You can also click “Request Info” to download and parse the metadata file, which is a good way to make sure the URL and file format are correct. If you have multiple plugins using this library, each plugin gets its own Debug Bar panel.

New $debugMode Setting

You can set $updateChecker->debugMode to true to make the library report errors that it would usually ignore. For example, if it gets an HTTP error while trying to download plugin information, it will usually fail silently and treat it as “no updates available”. With debug mode enabled, it will trigger a PHP warning instead. Debug mode will be enabled automatically if WP_DEBUG is enabled.

New getUpdate() Method

Previously there was no good way to get information about available updates from the update checker instance. Sure, the updates would show up just fine in the WordPress UI, but if you wanted to get the update details from inside your plugin, you had to jump through quite a few hoops.

In this version, you can just call getUpdate(). It returns an instance of PluginUpdate if there is an update available, or null otherwise. Note that this method uses the internal cache, so use checkForUpdates() instead if you want the most recent information.

Other Changes

• Added a resetUpdateState() method. It clears the update cache, last check timestamp and last checked version number.
• checkForUpdates() now returns the update details, if any. It didn’t return anything in the previous version.
• You can use the new puc_pre_inject_info-$slug filter to modify the update just before it’s passed to WordPress.
• Store cached updates as generic StdClass objects to prevent the “Tried to use an incomplete object” error on sites that use an object cache.
• Fixed an incompatibility between this library and WooThemes plugin updater that would cause no updates to show up even if everything was configured correctly. The problem: both libraries use the plugins_api filter, but the WooThemes updater throws away the response returned by other plugins and breaks my update checker.
• Minor code clean-up.

We’ve all been there. Trawling the admin menu, looking for that elusive link that will actually let us use the awesome new plugin we just installed. Granted, it usually takes only a few moments to find it, but it’s still annoying and unnecessary. Why not just tell the user how to get to right admin page? (Some plugins do, but in my experience they’re the exception, not the rule.)

If you’re a plugin developer, you can make your users’ life a little easier, and the first-run experience a little smoother, by displaying a small notification that explains how to get to the plugin’s admin page. Example:

In this post, I’ll show you how you can add a notice like that to your plugin. First, I’ll give you the code, and then I’ll explain how it works.

The Code

<?php
function example_display_menu_notice() {
	//Replace these with your plugins' values.
	$pageSlug = 'example-settings-page';
	$parentSlug = 'options-general.php';
	$noticeOption = 'example_show_menu_notice';

	//Only show the notice to users who can access the menu page.
	//Replace 'manage_options' with the appropriate capability.
	if ( !current_user_can('manage_options') ) {
		return;
	}

	$showNotice = get_option($noticeOption, null);

	//Hide the notice when the user first visits the plugin page
	//or when they dismiss it manually.
	$isPluginPage = $GLOBALS['pagenow'] == $parentSlug && $GLOBALS['plugin_page'] == $pageSlug;
	$isNoticeDismissed = isset($_GET[$noticeOption]) && $_GET[$noticeOption] == 'hide';
	if ( ($isPluginPage || $isNoticeDismissed) && ($showNotice !== false) ) {
		$showNotice = false;
		update_option($noticeOption, false);
	}

	if ( $showNotice ) {
		$dismissUrl = add_query_arg($noticeOption, 'hide');
		$dismissUrl = remove_query_arg(
			array('message', 'settings-updated', 'activate', 'deactivate'), 
			$dismissUrl
		);

		printf(
			'<div class="updated">
				<p>
					Tip: Example Plugin\'s admin page is at
					<a href="%s">Settings -> Example Settings</a>.
				</p>
				<p><a href="%s">Dismiss</a></p>
			 </div>',
			//Replace this with your admin page URL.
			esc_attr(admin_url('options-general.php?page=example-settings-page')),
			esc_attr($dismissUrl)
		);
	}
}
add_action('admin_notices', 'example_display_menu_notice');

//Enable the notice when the plugin is activated.
function example_enable_menu_notice() {
	//Only enable it not already enabled/disabled.
	if ( get_option('example_show_menu_notice', null) === null ) {
		update_option('example_show_menu_notice', true);
	}
}
register_activation_hook(__FILE__, 'example_enable_menu_notice');

//Clean up the DB option upon uninstallation.
function example_delete_notice_flag() {
	delete_option('example_show_menu_notice');
}
register_uninstall_hook(__FILE__, 'example_delete_notice_flag');
?>

How It Works

Okay, now lets examine the code.

We’ll start with example_display_menu_notice(). This is the function that will display the notice. At the top of the function, we have a bunch of variable declarations:

//Replace these with your plugins' values.
$pageSlug = 'example-settings-page';
$parentSlug = 'options-general.php';
$noticeOption = 'example_show_menu_notice';

Here we just set up some variables that will be used later in the script.

• $pageSlug – the slug you used when registering your menu page.
• $parentSlug – the slug of the parent menu. For example, if your page is part of the the “Settings” menu, then the parent slug will “options-general.php”, and if it’s under “Posts” then the parent slug will be “edit.php”.
• $noticeOption – the DB option we’ll use to store the notice state (visible or hidden).

if ( !current_user_can('manage_options') ) {
	return;
}

Naturally, we only want users who can actually access our menu page to see the notice. So we check if the current user has the necessary capability and bail out of the function if they don’t.

$showNotice = get_option($noticeOption, null);

//Hide the notice when the user first visits the plugin page
//or when they dismiss it manually.
$isPluginPage = $GLOBALS['pagenow'] == $parentSlug && $GLOBALS['plugin_page'] == $pageSlug;
$isNoticeDismissed = isset($_GET[$noticeOption]) && $_GET[$noticeOption] == 'hide';
if ( ($isPluginPage || $isNoticeDismissed) && ($showNotice !== false) ) {
	$showNotice = false;
	update_option($noticeOption, false);
}

This block of code determines whether we should show the notice or not. First, we check the DB option I mentioned later. It can either be true (= show the notice) or false (= don’t show the notice). If the option doesn’t exist yet, we’ll get a null instead. More on that later.

Next, we check if the user is currently viewing our menu page ($isPluginPage). If they are, then they obviously know where the page is and there’s no need to display the menu notice any more. To determine what the current page is, we check two global variables that are set by WordPress:

• $pagenow – the current file. For example, this will be “options-general.php” if we’re on the “Settings -> General” page or any plugin page that’s part of the “Settings” menu.
• $plugin_page – the slug of the currently open plugin page. If the current page was not created by a plugin, this will be null instead.

After that, we check if the user has clicked the “Dismiss” link. As we’ll see later, this link has a URL similar to “current-page-here?example_show_menu_notice=hide”. So we just check if the right query argument is there and is set to “hide”.

Finally, if either of the above conditions is met, we check if the notice isn’t already disabled ($showNotice !== false) and hide it by setting $showNotice and our DB option to false.

The second half of example_display_menu_notice() is what actually displays the notification message. After making sure that yes, we should show the notice, we build the URL for the “Dismiss” link:

$dismissUrl = add_query_arg($noticeOption, 'hide');
$dismissUrl = remove_query_arg(array('message', 'settings-updated', 'activate'), $dismissUrl);

As I mentioned before, the link is basically the current URL + an extra query argument that we set to “hide”.

We also need to remove a couple of arguments from the URL to avoid confusing the user. WordPress uses these arguments throughout the Dashboard to indicate the result of various operations like updating posts, saving settings, activating plugins and so on. If we leave them in and the user clicks the “Dismiss” link on a page that’s currently showing one of those messages, they’ll get the same message again, which can be misleading.

And finally, there’s this big printf() call:

printf(
	'<div class="updated">
		<p>
			Tip: Example Plugin\'s admin page is at
			<a href="%s">Settings -> Example Settings</a>.
		</p>
		<p><a href="%s">Dismiss</a></p>
	 </div>',
	//Replace this with your admin page URL.
	esc_attr(admin_url('options-general.php?page=example-settings-page')),
	esc_attr($dismissUrl)
);

This is what actually outputs the notice. Make sure to customize the message to suit your plugin, and replace options-general.php?page=example-settings-page with the URL of your menu page (relative to /wp-admin/).

To make the message show up in the right place, we’ll hook the display function to the admin_notices action. This action is run right before the main content of each Dashboard page, and that’s where WordPress displays most of its notifications and error messages.

add_action('admin_notices', 'example_display_menu_notice');

Next, we have two considerably simpler functions. The first, example_enable_menu_notice(), enables the notification when the plugin is activated:

function example_enable_menu_notice() {
	//Only enable it not already enabled/disabled.
	if ( get_option('example_show_menu_notice', null) === null ) {
		update_option('example_show_menu_notice', true);
	}
}
register_activation_hook(__FILE__, 'example_enable_menu_notice');

If the example_show_menu_notice option does not exist, we set it to true.

Now you might ask – why go to the trouble of explicitly enabling the notice upon activation, instead of just treating it as visible-by-default and hiding it when the user dismisses it or visits our page? The answer is this: we don’t want to annoy our existing users.

It’s a good idea to tell new users how to get to your plugin’s admin page(s). But if we do it to a user who just upgraded from an older version of the plugin, they’ll probably be annoyed because we’re telling them stuff they already know.

By enabling the notice on activation, we avoid this problem. The activation hook only runs when a plugin is installed or manually deactivated and re-activated. It does not run when you upgrade a plugin.

Finally, we want our plugin to be a good citizen and clean up after itself. The second short function is example_delete_notice_flag(), and it does just that by removing our DB option when the plugin is uninstalled.

function example_delete_notice_flag() {
	delete_option('example_show_menu_notice');
}
register_uninstall_hook(__FILE__, 'example_delete_notice_flag');
?>

This concludes today’s tutorial. If you have any questions or other feedback, leave a comment below.