Sniffing the WordPress Plugin API

During some recent troubleshooting of WordPress events being called in the plugin Instagrate to WordPress for a bug fix release, I came across a useful plugin on the WordPress repository built especially for plugin developers by Jeff SayreWordPress Hook Sniffer.

Sniffer what?

Like a network packet analyser (or sniffer), the WordPress Hook Sniffer intercepts and logs a stream of data. In this case the data is the hook events from the Plugin API that WordPress runs on a request. The plugin outputs the stream of events and the sequence they are fired to either a text file or the screen.

WordPress allows plugin developers to ‘hook’ custom functions onto the core events. Hooks can be in the form of Actions and Filters.

What is an Action?

An Action is a specific point in the WordPress core sequence of loading events. A plugin can hook multiple functions to multiple actions.

For example, your plugin needs to add a link to its settings page under the ‘Settings’ menu. You would create a function to add an options page:


public static function add_settings_menu() { 
     add_options_page( 'Instagrate to WordPress', 
                       'Instagrate to WordPress', 
                        1, 
                       'instagrate-to-wordpress, 
                       'settings_page');
}

You would then ‘hook’ the function ‘add_settings_menu’ onto the admin_menu action:


add_action('admin_menu', 'add_settings_menu');

Check the WordPress add_options_page→

What is a Filter?

A Filter is a way of changing certain text that WordPress uses before it is served up to screen or written to the database. This is very helpful for plugin and theme developers.

A classic example is the changing the length of the excerpt of a post. You would create a function to return a custom excerpt length:


function pvw_excerpt_length($length) {
       return 35;
}

You would then ‘hook’ the function ‘pvw_excerpt_length’ onto the excerpt_length filter:


add_filter('excerpt_length', 'pvw_excerpt_length');

Configuring the plugin

The plugin is very simple to set up. First radio button group allows you to enable or disable the logging. The next part allows you to configure the output options:

WP Hook Sniffer Options

There is a detailed description of each option here, but you really want to be selecting all to get a clear picture of what is going on. And lastly set the output location of the sniffing. Output to file for easier analysis in a text editor.

The Analysis

The output is comprehensive. The first section lists all the added action and filter hooks. It’s always best to check your function is being hooked into the correct function:


317: add_action( 'wp_loaded', 'instagrate_to_wordpress::auto_post_images' ) 
Called from: /.../wp-content/plugins/instagrate-to-wordpress/instagrate-to-wordpress.php | 
line #: 60 --> Time Added: 1331855684.0738

Then check out the ‘Action and Filter Function Array’ section. This lists the array of hooks and the functions hooked into them, in order. The real crux of the analysis is the section which lists the ‘Action Event Firing Sequence’. This has a timestamped list of all the actions that are fired. This is very helpful in working out what’s happening where, when and why. For example, an early version of the plugin had it’s main function hooked into the loop_start so it only added new posts when the blog page was requested. However, this was poor approach and resulted in the function being called multiple times on page when widgets were in play that also used the loop.

After playing around with the init and wp_loaded hooks, but realised that the function was getting called on every page load, admin, post, category, everything. That’s when after trawling the WordPress API reference I came across the template_redirect hook. This is the earliest hook point during the page load that can interrogate the WordPress core to work out what type of page is being served. You can use the function is_home() to check if it’s the blog page that is being loaded and action your script accordingly.

The bug fix is still on going, but discovering this plugin has added another level of visibility into the inner workings of the WordPress core and is a must for any plugin or theme developer.

Further reading

WordPress Plugin API→
WordPress Plugin API Reference→
Introducing WordPress Hook Sniffer: a Developer Plugin→
WordPress Hooks, Barbs, and Snags→

About Iain

I build things with WordPress and PHP. I also make free and premium WordPress plugins, most notably Instagrate Pro. I curate WP App Store.