Hooks are a way for one piece of code to interact/modify another piece of code at specific, pre-defined spots. They make up the foundation for how plugins and themes interact with WordPress Core, but they’re also used extensively by Core itself.
There are two types of hooks: Actions and Filters. To use either, you need to write a custom function known as a Callback, and then register it with a WordPress hook for a specific action or filter.
Actions allow you to add data or change how WordPress operates. Actions will run at a specific point in the execution of WordPress Core, plugins, and themes. Callback functions for Actions can perform some kind of a task, like echoing output to the user or inserting something into the database. Callback functions for an Action do not return anything back to the calling Action hook.
Filters give you the ability to change data during the execution of WordPress Core, plugins, and themes. Callback functions for Filters will accept a variable, modify it, and return it. They are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output. Filters expect to have something returned back to them.
Actions vs. Filters
The main difference between an action and a filter can be summed up like this:
- 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.
Said another way:
- an action interrupts the code flow to do something, and then returns back to the normal flow without modifying anything;
- a filter is used to modify something in a specific way so that the modification is then used by code later on.
The something referred to is the parameter list sent via the hook definition. More on this in later sections.
Actions and filters are simply two different types of events. Remember that WordPress refers to events as “hooks”. The difference between them is predicated on how WordPress handles the hook in question. Some hooks are designated as action hooks, others as filter hooks. When you link one of your functions to a filter hook, your function must accept an input and return an output because it is intended to modify or “filter” output. When you link a function to an action hook, your function is not passed input parameters, and any value returned is simply ignored. It is all a matter of how WordPress handles a given hook.
The truth of the matter is that the architecture here is showing its age, and there are some caveats that can be confusing. Actions and filters are simply types of events, and the add_action() and add_filter() functions are actually one and the same – one function merely references the other. If you are curious, have a look for yourself inside the /wp-includes/plugin.php file. In other words, you can replace any instance of add_action() with add_filter() and vice versa, and it will have no effect on the functionality of your plugin. They both simply tie a WordPress event to a function you have defined. Even though the add_action() and add_filter() functions are fundamentally the same, we do not recommend that you swap them! There is a recommended usage here that should be followed for mnemonic purposes.
both functions tie to an event, and the behavior of the event is determined by the event in question, not by the function used to reference it.
actions and filters are simply classifications of events, and the behavior of a particular event is inherent in the event itself, not in the function we use to reference it. In other words, admin_ footer and admin_head are action-events, not filter-events, and they remain actionevents no matter how we hook into them.
A function called by an action event does not accept or return input, whereas a function called by a filter does.