What are WordPress hooks and how to use them?

In WordPress theme and plugin development hooks are used to modify or extend WordPress core functionality without modifying the WordPress core files. There are two types of hooks: actions and filters. To use either, you need to write a custom function (callback) and then register it with a WordPress hook for a specific action or filter. The difference between actions and filters is summed up on wordpress.org:

• an action takes the info it receives, does something with it, and returns nothing. In other words: it acts on something and then exits, returning nothing back to the calling hook.
• a filter takes the info it receives, modifies it somehow, and returns it. In other words: it filters something and passes it back to the hook for further use.

Actions

How to add an action

The process of adding an action have two steps:

• create a callback function
• hook your callback function to an action.

Let’s create a function which saves additional metadata to a WordPress post:

If you put this piece of code in your wordpress theme or plugin, it does nothing for now. To make it work, you have to hook the function save_custom_metadata to an action. After a quick Google search on “WordPress save post hook” the best option to achieve our goal is to use the save_post hook like this:

As soon as you add this line to your theme or function, function save_custom_metadata will save your metadata to every new post. The add_action hook parameters are as follows:

• target hook (save_post in our example) – required, the name of the action
• callback function (save_custom_metadata in our example) – required, the name of the callback function
• priority (10 in our example) – optional, the priority of our callback function, the default value is 10. Many callback functions can be hooked to a single action, function with a higher priority will run after the lower priority functions.
• number of arguments (2 in our example) – optional, number of arguments to receive in the callback function. In the example when WordPress runs the save_post hook, it passes two parameters to the callback function:
  
  do_action( 'save_post', $post->ID, $post );

  1 2 3

  do_action( 'save_post', $post->ID, $post );

  
  In case we don’t need the $post parameter in our callback function, we can change number of arguments in our hook and callback function:
  
  add_action('save_post', 'save_custom_metadata', 10, 1); function save_custom_metadata($post_id){ // save metadata }

  1 2 3 4 5 6 7

  add_action('save_post', 'save_custom_metadata', 10, 1);   function save_custom_metadata($post_id){     // save metadata }

Filters

The process of adding a filter have also two steps:

• create a callback function
• hook your callback function to a filter and return the changed value.

Let’s create a callback function which always adds the string “Hello world” to the beginning of the post content:

To hook on Worpdress the_content filter, you have to add the next line to your code:

The parameters of add_filter are the same as in add_action:

• target hook (the_content in our example) – required, the name of the filter
• callback function (custom_hello_world_function in our example) – required, the name of the callback function
• priority (10 in our example) – optional, the priority of our callback function, the default value is 10. Many callback functions can be hooked to a single filter, function with a higher priority will run after the lower priority functions.
• number of arguments (1 in our example) – optional, number of arguments to receive in the callback function.

How to define a custom hook in your theme or plugin

In case you’re working on a custom theme or plugin, you might want to add actions and filters into your code. These “entry points” (hooks) will allow other developers to modify or extend the functionality of your product without changing your code.

To create a custom action hook, add a line to your code where the callback function should be executed as follows:

Make sure to use a unique action name which is the first parameter in the do_action method (freelancedev_custom_hook_name in our example). The best way is to add a custom prefix to avoid collisions (“freelancedev_” in our example). The action name in do_action is followed by the list of optional variables passed to the callback function ($paremeter1 and $paremeter2 in our example).

To create a filter, the process is pretty much the same for one exception: callback function will have a return value, always make sure to process it accordingly. Add the next line to its intended place in your code:

Unhooking actions and filters

If you want to disable a callback function from add_action() or add_filter(), you can use remove_action() and remove_filter(). It allows you for example to disable some hooks in a plugin which distrupts your sites functionality/optimization.

For example, we can remove our save_custom_metadata callback function created earlier from the save_post hook with the line