Using Filters in WordPress

Filters in WordPress are one of the mechanisms which allows the WordPress core system to call and run new code written after the core was written. They are one of the first conceptual ideas that you need to understand when you start developing in wordpress, because the very first rule of WordPress development is ‘you don’t change the core wordpress code’.

Why is changing core code a bad idea? Well, imagine that you have found just the place in the core code where you want to inject your fantastic new method which will revolutionise the way your site works. The edit the file, make the change and test it. Everything looks great so you push the change up to your live site and sit back and bask in the glow of your accomplishment. Then of course, there is an update to the core wordpress files and all your edits are removed.

So that is the main reason you don’t make changes to core WordPress files; Once there is an update to wordpress your changes are gone and you would have to make them again. Another reason is that the internal arrangement of the code inside the core can change over time and even if you organised to patch the core code each time a release happened you could easily run into difficulties.

So the way WordPress allows you to interact with the core code without making edits is by the way of two similarly named methods called Actions and Filters. Simplistically, actions allow you to do things like alter queries prior to fetching content and filters are generally used to alter content which has been fetched from the database. I will deal with actions in a future post on Develop with WordPress – this post deals with filters in WordPress.

How do Filters in WordPress Work?

A filter is a named ‘hook’ which a developer can register code against – quite literally it allows you to ‘hook’ your code into the core at certain defined places. The way this works is that at certain predefined points in the core code, there are checkpoints where a list of registered functions are called with the response data passed to the function so that it can be amended or replaced.

As an example, suppose you want to insert a notice at the start of every post on your site to inform your readers that the site will be off line for an hour. You want it to appear after the title but before any of the actual post content is displayed.

One way to do this would be to register some code to run against a filter called ‘the_content‘.

add_filter('the_content', 'add_my_content');

function add_my_content($content) {
  // Do stuff to $content

  $content = '<h2>This site will be off line in 30min for approx 1 hour</h2>' . $content;

  return $content;
}

This is a simple and I admit a rather manufactured use of a filter, but it demonstrates how it can be used. At the point the data is prepared to be used as the content pane in the response, our method is called and passed the value of the content. We can augment it with our message and then return it for the core code to use in the normal way.

There is one obvious question raised at this point – if there are two filters registered against the same hook, which one will be called first. Well the answer is that the functions will be called in the order they were originally registered but because it isn’t possible to know if other plugins have registered their filters before yours, there is also a way to affect the order by passing a third parameter to the add_filter call. For example:

add_filter('the_content', my_filter, 5);

This third argument acts as a priority indicator. If no argument is supplied the default value of 10 is used so a number lower than 10 will indicate that you want your filter processed before other filters and a number above 10 indicates you want your filter processed after other filters.

Just for the record, there is also another parameter which can be added to the add_filter call, which is another integer and is used to set the number of arguments which will be sent to the method registered against the hook. This sounds a bit confusing, but different filter hooks can supply different numbers of arguments and the extra parameter to the add_filter call allows you to fine tune your function.

There is a list of filter hooks available at this url which gives you an idea of the calls available, but a really useful plugin is Simply Show Hooks which gives a visual indication of when different filters are called during the creation of a response page.