Function Documentation

WordPress Function Documentation Progress

Informal Roadmap: Step 1 Completed

I finished the first step of the informal roadmap for the wp-includes folder. I’m halfway through with completing the second step, but really, it isn’t so hard to complete those steps. Steps 3, 4, and 5 are the most difficult and time consuming ones to complete.

As always, I’m working on fully completing several files while completing the rest of the steps. I figure if I complete the steps, it won’t seem as difficult and time consuming and I can get many files completed at once.

Advertisements

January 10, 2008 Posted by | WordPress | , | Leave a comment

Writing Plugins: The ‘all’ Hook

The ‘all’ hook is run on every action and filter hook. It is good for debugging and not much else. Also, prior to WordPress 2.5, the ‘all’ hook was broken and shouldn’t be hooked into.

The fix removes the logic that merges the all hook into the rest of the other hooks. This should have a nice benefit of speeding up the plugin cycle. The all hook will also only be processed if there is a function that was added to it. For almost all users, they will never run the all hook.

The ‘all’ hook is technically an action since it does not offer an interface for returning data to other functions that are in the ‘all’ hook. However, it will run for all actions and filters, but will not have access to the filter contents.

Well, for filters, the ‘all’ hook will have access to the initial parameter value or values if there is more than one parameter (more on that later), but will not have access to the completed value after all of the functions in the hook have processed the initial value.

Adding a Function to the ‘all’ Hook

add_action('all', 'myplugin_all_hook');

function myplugin_all_hook( $parameters ) {
    // Do stuff here
}

The all hook has access to the parameters that were passed to the hook as an array and that will be passed to the functions. The ‘all’ hook does not have access to manipulate those parameter values before they get to the filter or action functions.

The $parameters is an array, which holds all of the values for from each of the parameters. You can count the array, test the contents of the parameters, test the types of the values.

Use Cases

What the ‘all’ hook can do however is a few evaluations.

  1. Do sanity checks against how many parameters the current hook (Will be discussed in a later post) should have verses how many were actually passed.
  2. Count how many times a hook was called during a run of WordPress and for each page. (The ‘all’ hook will not be able to profile how long each hook took to process however.)
  3. Using debug_backtrace(), can figure out which functions called the hook.
  4. Fine tune your plugin by seeing what the hook you are plugin to is giving your function.

Those are the common use cases of the ‘all’ hook. However, like it has already been stated, only debuggers are likely to plugin to the ‘all’ hook. Most plugin authors and users should not concern themselves. However, if you wish to debug the hooks, then there is a built-in way to do so.

January 10, 2008 Posted by | Writing Plugins Series | , , , | Leave a comment