There are two main ways to extend or customize existing WordPress plugin without editing the code directly – filters and actions (as a whole called “hooks”). The WordPress Codex does a good work of documenting the functions for actions and filters. It does not do such a good job in giving easy to understand example how to actually use this to do something useful. We are going to fix the problem with this tutorial.

Before going further you must have one thing in mind – the plugin that you are going to customize must be customization-friendly and offer at least some hooks. Example of such plugin is our Namaste! LMS with its Developer’s API. If you are writing a plugin it’s good to think about adding do_action and apply_filters calls on the most important places.

In this tutorial I’m going to use a couple of examples from Namaste! LMS and our other developer-friendly plugin WatuPRO to illustrate the usage of only the 4 most important action / filter functions:

• do_action
• add_action
• apply_filters
• add_filter

Let’s go!

Filters

The below chart will give you basic idea how filters work. Then we’ll provide some examples.

Filters are used mostly when you want some content to be modified before displayed or sent to user. You can apply filters on text but not only – there are a lot more creative ways to use filters. Here are a couple examples from Namaste! LMS:

1. All the places where courses are selected to be shown to the user in Namaste! LMS have this hook:
$courses = apply_filters('namaste-reorder-courses', $courses);

What does it do? It allows other plugins to apply changes directly to the $courses array. And Namaste! PRO uses exactly this filter to apply the custom order of courses to the array by catching the filter:

add_filter( 'namaste-reorder-courses', array('NamastePROCourses', 'reorder_filter'));

There are several things that you must understand here:

a) The “source” plugin (the one that you will be customizing) must provide the proper filter by calling apply_filters($tag, $value) on the variable that will be modified. The first argument is the tag of the filter. It’s just unique name that will then be used by other plugins in the add_filter($tag, $function) call. When the name matches, the function defined in add_filter will be executed over the content of $value from apply_filters in the other plugin. Thus you can modify the $value (in our cases $value is the variable $courses).

b) The extending plugin must catch the filter with add_filter() call as explained above. But in order anything to happen the extending plugin should also define the function or method mentioned in the add_filter call (the second argument called $function). Look at the code again:

add_filter( 'namaste-reorder-courses', array('NamastePROCourses', 'reorder_filter'));

This means your customization plugin should have a class called NamastePROCourses with method called reorder_filter.

c) The apply_filters() call returns the modified $value which should also be returned by the function defined by add_filter(). It’s not important how exactly the method reorder_filter works but it must return the modified variable:

static function reorder_filter($courses) {
   // do something with $courses inside the method
   // not shown here

   return $courses; // return the modified variable
}

Only this way the $courses variable will be modified in the original plugin.

d) Multiple plugins can apply changes to the content using the same filter tag. So you can write your plugin that will for example add more properties to the $courses array, slice it, erase it, change it to something completely different and so on.

e) Do not rely on order of filters execution. When writing a custom plugin you should never assume that add_filter() calls from other plugins will be executed before or after your call.

f) If no filters are defined with add_filter for a given tag, then the apply_filters call will return the original variable.

2. As you saw from the above example, you can filter not just text but any kind of variable – in our case it was an array. The below example will demonstrate a smart trick using text. We need to allow external plugin to apply user-based restrictions to the SQL query that selects courses. instead of working with the courses array, we just use SQL variable string that will be applied to the query:

$filter_sql = '';
$filter_sql = apply_filters('namaste-course-select-sql', $filter_sql, $user_ID);

In the above example the variable $filter_sql (which is after that used inside the SQL query string) is first initialized as empty string. This way if no plugin defines add_filter on the namaste-course-select-sql tag, the string will remain empty and the query will remain as is. However if another plugin catches this filter and adds some SQL to it, the query which contains the $filter_sql variable will also be changed!

The above example also passes additional argument so the add_filter call needs two extra arguments:

add_filter( 'namaste-course-select-sql', array('NamastePROClass', 'course_select_sql'), 10, 2);

Check the add_filter documentation to understand why they are required.

Actions

Actions don’t return value and don’t let you modify variables but are probably even more powerful and easier to understand than filters. Actions let you notify other plugins that something in your plugin has happened. Then the other plugins can act based on it. You can also pass arguments to actions. The “source” plugin must call do_action($tag) and the receiving (customization) plugins must call add_action($tag, $function) with the same $tag to catch the action and call the $function. Here are a couple of examples:

1. Probably the most used action call in WatuPRO is the “waturpo_completed_exam” action called when a quiz is completed:

do_action('watupro_completed_exam', $taking_id);

This call sends the ID of the just taken quiz record so other plugins can use it. And they do. For example the Play Plugin catches this action to update user’s level, badges, points balance etc:

add_action('watupro_completed_exam', array($_user, 'update_meta'));

The variable $_user in this case is instance of the WatuPROPlayUser user object which has method update_meta. The method update_meta takes one argument – the taking ID – and does things with it:

function update_meta($taking_id){ /* do something here */}

Of course, just like with filters, the call to add_action must use the the same tag as the call to do_action to catch the action – in this case the tag is watupro_completed_exam.

2. Here’s a bit different example, this time from Namaste! LMS. At the end of creating the menu of the plugin we add the following simple do_action call, no arguments needed:

do_action('namaste_lms_admin_menu');

This lets other plugins hook their links under the Namaste! LMS menu so their extra options nicely align in it instead of creating more top-level menu links. This action is caught by Namaste! Reports, Namaste! Connect, Namaste! PRO, the InstaMojo integration plugin and many more. If you write your own plugin for Namaste! LMS I recommend using the same action (in case you need to add pages to the menu). Example call:

add_action('namaste_lms_admin_menu', array('NamastePRO', 'menu'));

Then the menu() function in NamastePRO class simply adds its own add_submenu_page() calls to add more links (note that the add_submenu_page() parent slug must also be properly defined).

Actions and filters give you huge options for customization and the best of it: without touching the code of the original plugin. Beautiful! Of course this is only possible if the original plugin defines do_action and add_filter calls in the proper places. If it doesn’t you can try to request the original developer to add some hoks. Most will not refuse because adding a hook here and there is not hard and makes the plugins easier to extend.

If there’s anything unclear in the above explanations, please ask in the comments.