The What
Description
This construct fires the specified event, which means it loops through the event registry lookup table and calls each registered callback one-by-one. The callbacks are pre-registered for this event using add_filter
.
Parameters
event_name
- The name of the event (filter hook) to fire.
value
- The value which is changeable by each of the registered callbacks.
...
- optional. Additional arguments to pass to each registered callback.
Return Values
Returns the $value
after all of the callbacks have processed, meaning the value may be different than what was passed into when the event fired.
Unlocked for Everyone
We unlocked all of the content for this article to show you what you would get if you were a Pro member. Enjoy learning about apply_filters
.
Plugins RepoPro
The following link will provide you access to the plugins that are used in the following videos. You can build the starter plugin using this lab.
Show It in ActionBasic
Let’s see the apply_filters
function in action. In this video, you will see how it works. You will also see real-world examples in both WordPress Core and the Genesis framework.
You get WET when you swim. Stay DRY when you code.
Go Deep – OverviewPro
In this video, you will walk through apply_filters
in the WordPress Core source code and get a general overview of all of the tasks within this one function. In the sequent videos below, you will reverse engineer each of the sub-tasks in core.
Go Deep – ArgumentsPro
In these two (2) videos, you will walk through how the arguments are assembled and then sent to each registered callback. Remember that each one specifies how many arguments it wants when registering with add_filter
.
Also notice that only two (2) parameters are declared in the function’s parameter list, i.e. apply_filters
. You will reverse engineer WordPress Core to see how the arguments are pulled out of PHP memory using func_get_args
.
There’s much to cover to really know how and why the arguments are processed and then sent to each callback.
Go Deep – “all” EventPro
In this video you will explore and reverse engineer the “all” event as well as the function _wp_call_all_hook
.
// Do 'all' actions first. | |
if ( isset($wp_filter['all']) ) { | |
$wp_current_filter[] = $tag; | |
$args = func_get_args(); | |
_wp_call_all_hook($args); | |
} |
This function is used in:
It works the same for all of these functions.
Go Deep – Check if in RegistryPro
In this video you will explore and reverse engineer WordPress Core
to see what happens if the event name does not exist in the registry.
if ( !isset($wp_filter[$tag]) ) { | |
if ( isset($wp_filter['all']) ) | |
array_pop($wp_current_filter); | |
return $value; | |
} |
-
Code example
Go Deep – What is $wp_current_filterPro
What is $wp_current_filter
? What is it’s purpose and intent? Let’s go deep into WordPress Core and discover what it does and why.
You might have noticed from the previous video that both actions and filters are stored in $wp_current_filter
. Why? What is the purpose? Let’s discuss it to avoid confusion.
-
Code example
Code. Eat. Code. Sleep. Dream about Code. Code.
Go Deep – Sorting the RegistryPro
Before we can call each of the callbacks, first we need to sort the registry, i.e. $wp_filter
. Why? To make sure they are in the proper order by the priority level. Let’s dig into WordPress Core to look at who the registry is sorted.
// Sort. | |
if ( !isset( $merged_filters[ $tag ] ) ) { | |
ksort($wp_filter[$tag]); | |
$merged_filters[ $tag ] = true; | |
} | |
reset( $wp_filter[ $tag ] ); |
Go Deep – Callback LoopPro
Now you will explore the hardest part of the Event Registry System, i.e. the callback loop. It is hard only because it uses quite a few PHP constructs that confuse people. Therefore, before watching these videos, stop and go watch these in the PHP Docx. Once you understand these constructs, then the callback loop will make so much more sense to you.
do { | |
foreach ( (array) current( $wp_filter[$tag] ) as $the_ ) { | |
if ( ! is_null( $the_['function'] ) ) { | |
$args[1] = $value; | |
$value = call_user_func_array( $the_['function'], array_slice( $args, 1, (int) $the_['accepted_args'] ) ); | |
} | |
} | |
} while ( next( $wp_filter[$tag] ) !== false ); |
In this first video, you will see that there are two separate loops, one that handles:
Let’s dig into the callback calling loop itself.
What this code does is not complex or difficult. Rather, what makes it hard to understand is the way that it’s written, as it is not as readable as it could be. Let’s refactor the loops to improve readability, simplify the code, and further help you to know the what and how of calling callbacks.
-
Refactored version
PHP Constructs
These are the PHP constructs used in WordPress Core for apply_filters
: