apply_filters() │ WP 0.71

Застосовує прикріплену до зазначеного фільтра PHP функцію.

Прикріплюється функція PHP до фільтра за допомогою add_filter() .

Використовується там, де потрібно змінити значення змінної (наприклад, надати можливість змінити оригінальний текст).

Використовується в плагінах і темах для створення хуків-фільтрів (зачіпок, що дають можливість змінити оригінальні дані).

Нові фільтри повинні мати унікальні назви і не повинні збігатися з назвами фільтрів, що вже є в WP.

Крім фільтрів у WP є ще події (actions), їх принцип роботи такий самий. Різниця лише тому, що фільтр повинен повернути отриману змінну, тобто. він фільтрує (змінює) дані, а подія дозволяє запустити функцію чи зробити щось ще у момент спрацьовування цієї події. Події запускаються функцією do_action()

Дивіться також аналогічну функцію apply_filters_ref_array() , яка дозволяє передавати параметри посилання.

1 раз – 0.000001 сек
(швидкість світла) | 50000 разів – 0.02 сек
(швидкість світла) |
PHP 7.0.32, WP 5.0.3

Хуків немає.

Повертає

Разное. Відфільтроване значення $value, яке передається функції-обробнику хука.

Використання

apply_filters($hook_name, $value, ...$args);

$hook_name (рядок) (обов’язковий): Назва фільтра.
$value (рядок/масив/число/об’єкт/логічний) (обов’язковий): Значення, яке передаватиметься функції у її першому аргументі, тобто – значення, яке потрібно відфільтрувати.
…$args (рядок/масив/число/об’єкт/логічний): Додаткові значення, які передаватиме фільтр функції.

Приклади

#1 Приклад фільтрації

Отримання відфільтрованого значення:

$value = apply_filters( 'filter_name', $value );

Відфільтрувати значення та вивести його на екран:

echo apply_filters( 'filter_name', $ value );

Передача додаткових аргументів для функції фільтра:

$value = apply_filters( 'filter_name', $value, $arg1, $arg2, ...);

Наприклад:

$value = apply_filters( 'filter_name', 'filter me', 'arg1', 'arg2');

#2 Приклад виведення відформатованого вмісту запису через фільтр.

Альтернатива функції the_content():

global $post;
echo apply_filters( 'the_content', $post->post_content );

нотатки

Global. WP_Hook[]. $wp_filter Stores all of the filters and actions.
Global. Рядок[]. $wp_current_filter Stores список поточних filtrів з поточним одним останнім.

список змін

З версії 0.71	Введено.
З версії 6.0.0	Formalizated existing and already documented `…$args` parameter by adding it до функції signature.

Код `apply_filters() apply filters` ^{WP 6.0.2}

wp-includes/plugin.php

function apply_filters( $hook_name, $value, ...$args ) {
	Global $wp_filter, $wp_current_filter;

	// 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 $value;
	}

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

	// Pass the value to WP_Hook.
	array_unshift($args, $value);

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

	array_pop($wp_current_filter);

	return $filtered;
}