Mar 102015
 
Article WordPress

One of the keys in the success of WordPress as one of the most popular content management systems lies in its flexibility to add new functionality, or modify the existing functionality, by means of plugins. WordPress plugins attach the extra functionality thy implement to “hooks” in the wordpress code.

Hooks are points defined in many places of the wordpress base code. A hook can be an action or a filter: filters are used when part of the HTML code being generated needs to be modified. The original HTML code is passed as an argument to the filter, and the filter return the modified code.This post explains the implementation details of action and filter hooks in wordpress.

WordPress functions called to generate the HTML code of the page

Every page that the web server delivers to be displayed in the client browser is composed of several elements. In most cases, the layout of the page includes a header, a navigation menu, the main content, a sidebar and a footer.

WordPress implements several functions that extract from the database the content of each of these elements. The theme used in the site calls these functions to generate the final HTML code delivered to the client.

The main functions of this kind are:

  • wp_head() – Generate the content inside the <head> section of the HTML document
  • get_header() – Generate the HTML code of the page heading, loading the “header.php” script in the active theme.
  • the_content() – Generate the HTML code of the main content of the page
  • get_footer() – Loads the page footer

Usually, a wordpress theme includes the scripts “index.php”, “header.php”, “page.php”, “single.php”, “footer.php”, etc. Each of these scripts calls the corresponding wordpress function to obtain the page content and send the final HTML code to the client.

Action hooks and Filter hooks

Action hooks are defined in the base code of wordpress by means of calls to the function do_action(“action-tag”). Similarly, filter hooks are defined by calls to the function apply_filters(“filter-tag”). These calls are normally found in wordpress functions that generate the HTML code for different parts of the page such as wp_head(), the_content(), etc:

function action filter
wp_head do_action(‘wp_head’)
get_header do_action(‘get_header’)
the_content apply_filters(‘the_content’)
get_footer do_action( ‘get_footer’)

The theme used, and the active plugins, attach to the hooks PHP functions, implementing the desired action or filter, by means of calls to add_action() and add_filter(). Then, at the time do_action($tag) or apply_filters($tag) are executed, all functions attached to the given tag are executed

Actions and filters share many aspects (in fact, the function add_action() is implemented as an alias to add_filter()). The main difference between them is in that filters return a value, which results from applying the intended modification to the argument received.

Sample action hook

As an example, we will insert a comment in the <head> section of the HTML document. We can do this by attaching a function my_comment() to the ‘wp_head’ action tag. First, write the function that outputs the comment:

function my_comment() {
    // This function just prints a HTML comment

    echo "<!-- This is a HTML comment -->\n";
}

Next, a call to add_action is done to hook the my_comment() function to the ‘wp_head’ action tag:

add_action ( 'wp_head', 'mi_comentario');

Both the function definition and the call to add_action are put in the “functions.php” script of the active theme.

We could use this same procedure to load a javascript library or a CSS document to the <head> section.

Sample filter hook

The HTML code of the parts that compose the page can be modified by the theme or by a plugin by hooking a filter function.

For instance, we have mentioned that the_content() functions defines a filter hook tagged as “the_content”. We can use this hook to replace the word “property” with “house” in the content of all posts and pages in the site. First, the function “replace_house”, implementing the desired filter, is added to the “functions.php” script in the active theme:

function replace_house($content) {
    return str_replace("property","house",$content);
}

Then, the function is hooked to the “the_content” tag with a call to add_filter, also in the “functions.php” script:

add_filter( 'the_content', 'replace_house' );

Additional arguments in the calls to add_action and add_filter

Both functions can receive the same additional arguments:

<?php add_action( $tag, $function, $priority, $num_arguments ); ?>
<?php add_filter( $tag, $function, $priority, $num_arguments ); ?>

$priority is a numeric value from 0 to 10 (default: 10). This argument is used to establish the order of execution of the set of functions hooked to the same tag. Functions with lower $priority values are executed first.

$num_arguments sets the number of arguments accepted by the function being hooked.

How to list all functions hooked to a tag

While developing a plugin, or to troubleshoot some unexpected behaviour in a website powered by WordPress, it is desirable to be able to list all the functions that the theme or other plugins have attached to an action o filter tag.

This can be done by adding to the theme’s “functions.php” script a function “list_hooked_functions”, defined as follows:

function list_hooked_functions($tag=false){
     global $wp_filter;
     if ($tag) {
         $hook[$tag]=$wp_filter[$tag];
         if (!is_array($hook[$tag])) {
             trigger_error("Nothing found for '$tag' hook", E_USER_WARNING);
             return;
         }
     }
     else {
         $hook=$wp_filter;
         ksort($hook);
     }
     echo "\n<!--\n";
     foreach($hook as $tag => $priority){
         echo $tag . "\n";
         ksort($priority);
         foreach($priority as $priority => $function){
             echo $priority;
             foreach($function as $name => $properties) echo "\t$name\n";
         }
     }
     echo "-->\n";
     return;
}

The function queries the global variable $wp_filter, which is used to store a reference to all functions hooked to action or filter tags.

An optional argument can be passed to list_hooked functions with the name of the tag whose attached functions we want to list. If no argument is given, all functions attached to all existing action and filter tags are returned.

list_hooked_functions outputs the result to standard output formatted as a HTML comment.

References

 Posted by at 9:49 am

 Leave a Reply

(required)

(required)