Introducing WordPress Hook Sniffer: a Developer Plugin
By Jeff Sayre
As a developer, one of the benefits to sophisticated Open Source projects like WordPress and BuddyPress is that a significant amount of foundational code is already in place. This makes adding additional functionality, additional value, to the platform easier. You just create a plugin.
As a developer, one of the downsides to Open Source projects like WordPress and BuddyPress is that a significant amount of foundational code is already in place. There are hundreds of functions, classes, methods, and general code that you never actually get to know. Sure, you might call them from within your code, you might know how and when to use them, but you more than likely do not understand how and why they work and what they actually do to accomplish their task.
Why? Because you were (more than likely) not part of the team that wrote the code, that figured out what each function was required to accomplish and in what ways that code would interact with other parts of the foundation.
This is exactly the situation I found myself in several weeks ago as I was trying to figure out why one of my custom do_action events in my BuddyPress Privacy Component was not working as I had expected. My investigation into this issue not only opened my eyes into the inner workings of WordPress’ Plugin API, but also helped me figure out why a few BuddyPress action events were not behaving as intended.
Understanding Hook Firing Sequence
How can you know the firing sequence of action functions or filter functions that you attach to existing WordPress and BuddyPress hooks? Why is this even important?
To answer the second question, read my article, WordPress Hooks, Barbs, and Snags. The answer to the first question is more difficult.
Since many internal WordPress and BuddyPress functions may be tying into the same action or filter hooks, there is no easy way to know the firing sequence of action functions or filter functions. Add to that the fact that 3rd-party external plugins can also tie into these same action or filter hooks and the issue becomes even more murky.
As I had a serious issue with a custom do_action event in my BuddyPress Privacy Component not working as expected, I set out to solve the first question. Although my problem appeared to be with my custom do_action event, I soon discovered that it was caused by another hook to which I had tied in to.
The result of my investigation: a new tool for WordPress and BuddyPress developers called the WordPress Hook Sniffer. What does this plugin do? It helps plugin developers determine the sequence in which action and filter functions are fired, providing a window into the inner workings of the WordPress Plugin API.
As with all of my other WordPress and BuddyPress plugins, this plugin is licensed under the GNU General Public License 3.0 (GPL).
Download WordPress Hook Sniffer and Donate!
You can download the WordPress Hook Sniffer via the WP Plugin Repository. Even more excitingly, you can help me support this plugin, encourage me to create new ones, and enable me to keep living by selecting a sponsorship level below and clicking the “Pay Now” button. Thank you!
Using the Plugin
WARNING: This plugin is to be used only in a development sandbox and not in a production environment. It is intended solely for use by plugin developers to help determine the sequence in which action and filter functions are fired. Use at your own risk. As this plugin should not be installed on an active WordPress-based site (a production site), no support for broken sites will be given. You have been warned!
As with all plugins, please read the installation instructions in the readme.txt file. You may find the FAQ in the readme.txt file useful. Also, if you have been using an older version of this plugin, the installation process is now much simpler—see this post for details.
- Once installed and activated, you will find a new menu option in the Settings menu
- Clicking on that will bring up the WordPress Hook Sniffer Settings screen. The first thing to do is look in the upper left-hand corner of the screen. See that gratuitous “Please Support My Work” section? Go ahead and select a nice, juicy amount and then click the “Pay Now” button. Your donation (in any amount) is greatly appreciated! Okay, enough begging.
- Next, read the “Usage Notes” section at the end of this article for a few additional bits of important information
- Finally, select “Enabled” in the Main Sniffer Settings section, choose what data you wish to view in the Output Options section, and then select where you would like the output to go in the Output Location section
- It’s that easy!
Output Settings Options
Whereas getting the WordPress Hook Sniffer to work is relatively straight forward, interpreting the output is a different story. What does all of that crap stuff mean?
Here is a brief overview of each of the output options and what information it can provide. However, to truly understand how to interpret the output and how best to use it in your development work, you will need to read my article, WordPress Hooks, Barbs, and Snags article.
A. Added Functions
Selecting this option outputs the special WP Hook Sniffer array that holds, in the order in which they were encountered during code execution, all add_action calls and add_filter calls. The file and line number from which a given function was triggered is also provided.
B. Removed Functions
Selecting this option outputs the special WP Hook Sniffer array that holds, in the order in which they were encountered during code execution, all remove_action calls and remove_filter calls. The file and line number from which a given function was triggered is also provided.
C. Action and Filter Function Array
This is the grandaddy, grandmommy, grandchild, Grand Ole Opry of output data. It contains the output of the $wp_filter array, the array that holds all of the added action and filter functions and is used by the do_action and apply_filters functions call to determine function firing order—although there is a twist here. You must read my article WordPress Hooks, Barbs, and Snags article to learn what it is.
D. Action Event Firing Order
This option contains the output of the $wp_actions array. A simple, one dimensional array that holds the sequential listing of all the do_action events that need to be processed. The events within this array used in conjunction with with corresponding data in the $wp_filter array determines the firing sequence of all action functions
E. Action Event Firing Sequence
Selecting this option outputs the special WP Hook Sniffer array that holds the sequential listing of do_action events with their corresponding fired action function(s). This listing shows you exactly the sequence in which each triggered action event fires its hooked action functions.
F. Filter Event Firing Sequence
Selecting this option outputs the special WP Hook Sniffer array that holds the sequential listing of apply_filters events with their corresponding fired filter function(s). This listing shows you exactly the sequence in which each triggered filter event fires its hooked filter functions.
- Reporting Bugs: If you find bugs or are having issues using this plugin, you can either post a comment in this article or visit the support forum for this plugin. Assistance in providing patches to this plugin is appreciated.
- Increasing Precision: If you want to see a more precise accounting of the execution time of a given function, you have to edit your php.ini file to increase the precision displayed for floating point numbers. Search your php.ini file for the entry:
precision = 12
and change that to:
; precision = 12
precision = 16
As you can see, I like to comment out any changes to my default php.ini settings just in case I decide to revert the changes later. This allows you to do so easily without having to remember or look up what the default setting is supposed to be.
Save your modified php.ini file and then restart your development server and you should now see the time-executed stamp displaying 6 significant figures instead of 2. This provides a sufficient level of detail.
- Text Output Issues: If you’re using SSL or are behind a proxy server, you may have issues when selecting to send the output to a text file. There are a few work arounds for this, but suffice it to say that since this plugin is to be used exclusively in a development sandbox environment, I will not be coding these into the plugin. If you must use this plugin with SSL or behind a proxy server, then simply select the screen output option. You can learn more about this in the PHP manual for the fopen function.
- Screen Output: When printing to screen, it may take a several seconds for output to finish. The output will start just below your theme’s footer.