apply_filters

The What

mixed apply_filters ( 
	string $event_name,
	mixed $value,
	mixed $...
);

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.

Get the code on Github

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.

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 .

This function is used in:

• apply_filters_ref_array
• do_action
• do_action_ref_array

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.

Code example

	add_filter( 'knowthecode', function( $value ){
	d( 'in the filter knowthecode ' . $value );
	}, 52 );
	add_action( 'loop_start', __NAMESPACE__ . '\demo_no_callbacks' );
	function demo_no_callbacks() {
	echo 'in demo_no_callbacks<br>';
	global $wp_filter;
	d( $wp_filter['knowthecode'] );
	remove_all_filters( 'knowthecode' );
	d( $wp_filter['knowthecode'] );
	d( array_key_exists( 'knowthecode', $wp_filter ) );
	$value = apply_filters( 'knowthecode', 'Hello there' );
	echo 'back from apply_filters';
	d( $value );
	}

view raw

apply_filters.php

hosted with ❤ by GitHub

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

	add_filter( 'knowthecode', function( $value ){
	d( 'in the filter knowthecode ' . $value );
	}, 52 );
	add_action( 'loop_start', __NAMESPACE__ . '\demo_no_callbacks' );
	function demo_no_callbacks() {
	echo 'in demo_no_callbacks<br>';
	global $wp_filter;
	d( $wp_filter['knowthecode'] );
	remove_all_filters( 'knowthecode' );
	d( $wp_filter['knowthecode'] );
	d( array_key_exists( 'knowthecode', $wp_filter ) );
	$value = apply_filters( 'knowthecode', 'Hello there' );
	echo 'back from apply_filters';
	d( $value );
	}

view raw

apply_filters.php

hosted with ❤ by GitHub

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.

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.

• call_user_func_array
• current
• next
• do-while
• foreach

In this first video, you will see that there are two separate loops, one that handles:

• Priority level loop – do-while, current, and foreach
• Callback calling loop – foreach

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

	function apply_filters( $tag, $value ) {
	// removed for brevity....
	// foreach ( (array) $wp_filter[ $tag ] as $priority_level => $callbacks ) {
	// $value = call_event_callbacks_for_this_priority( $callbacks, $args, $value );
	// }
	do {
	$callbacks = current( $wp_filter[ $tag ] );
	foreach ( (array) $callbacks 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 );
	array_pop( $wp_current_filter );
	return $value;
	}
	function call_event_callbacks_for_this_priority( $callbacks, $args, $value ) {
	foreach ( (array) $callbacks as $the_ ) {
	if ( is_null( $the_['function'] ) ) {
	continue;
	}
	$args[1] = $value;
	$callback_arguments = array_slice( $args, 1, (int) $the_['accepted_args'] );
	$value = call_user_func_array( $the_['function'], $callback_arguments );
	}
	return $value;
	}

view raw

apply_filters.php

hosted with ❤ by GitHub

PHP Constructs

These are the PHP constructs used in WordPress Core for apply_filters:

• foreach
• do-while
• current
• ksort
• call_user_func_array
• next
• array_slice
• array_pop
• empty
• isset
• return

Also See

• add_filter
• apply_filters_ref_array
• has_filter
• current_filter
• doing_filter
• remove_filter
• remove_all_filters