Calls the callback functions that have been added to a filter hook, specifying arguments in an array.

Description

See also

• apply_filters(): This function is identical, but the arguments passed to the functions hooked to $hook_name are supplied using an array.

Parameters

$hook_namestringrequired

The name of the filter hook.

$argsarrayrequired

The arguments supplied to the functions hooked to $hook_name.

Return

More Information

• This function can be useful when your arguments are already in an array, and/or when there are many arguments to pass. Just make sure that your arguments are in the proper order!
• Before PHP 5.4, your callback is passed a reference pointer to the array. Your callback can use this pointer to access all the array elements. Adding a filter and declaring a call back that hooks the above example filter could look like this:
  

add_filter('my_filter', 'my_callback');
function my_callback( $args ) {
//access values with $args[0], $args[1] etc.
}

Because the array was passed by reference, any changes to the array elements are applied to the original array outside of the function’s scope.

add_action('my_filter', 'my_callback', 10, 4 );
function my_callback( $arg1, $arg2, $arg3, $arg4 ) {
//access values with $args1, $args2 etc.
}

This method copies the array elements into the parameter variables. Any changes to the parameter variables do not affect the original array.

apply_filters_ref_array( 'my_filter', array( &$args ));

add_action('my_filter', 'my_callback');
function my_callback( &$args ) {
//access values with $args[0], $args[1] etc.
}

Because the original array was passed by reference, any changes to the array elements are applied to the original array outside of the function’s scope.

Source

function apply_filters_ref_array( $hook_name, $args ) {
	global $wp_filter, $wp_filters, $wp_current_filter;

	if ( ! isset( $wp_filters[ $hook_name ] ) ) {
		$wp_filters[ $hook_name ] = 1;
	} else {
		++$wp_filters[ $hook_name ];
	}

	// Do 'all' actions first.
	if ( isset( $wp_filter['all'] ) ) {
		$wp_current_filter[] = $hook_name;
		$all_args            = func_get_args(); // phpcs:ignore PHPCompatibility.FunctionUse.ArgumentFunctionsReportCurrentValue.NeedsInspection
		_wp_call_all_hook( $all_args );
	}

	if ( ! isset( $wp_filter[ $hook_name ] ) ) {
		if ( isset( $wp_filter['all'] ) ) {
			array_pop( $wp_current_filter );
		}

		return $args[0];
	}

	if ( ! isset( $wp_filter['all'] ) ) {
		$wp_current_filter[] = $hook_name;
	}

	$filtered = $wp_filter[ $hook_name ]->apply_filters( $args[0], $args );

	array_pop( $wp_current_filter );

	return $filtered;
}

View all references View on Trac View on GitHub

Changelog