Attaches the specified PHP function to the specified filter hook. Thus, when the filter is triggered, the value will be filtered by the specified PHP function.
A filter is a hook inside code through which you can «filter» any data. For example, during receiving and displaying some text from the database, you can change it «on the fly» and display the already modified version of the text. Thanks to the filters, for doing such text change we do not have to edit code in WP core files, but we can do it in our plugin or theme php file.
WordPress offers filter hooks to allow plugins to modify various types of internal data at runtime. A plugin can modify data by binding a callback to a filter hook. When the filter is later applied, each bound callback is run in order of priority, and given the opportunity to modify a value by returning a new value. The following example shows how a callback function is bound to a filter hook. Note that $example is passed to the callback, (maybe) modified, then returned:
function example_callback( $example ) < // Maybe modify $example in some way. return $example; >add_filter( 'example_filter', 'example_callback' );
Bound callbacks can accept from none to the total number of arguments passed as parameters in the corresponding apply_filters() call. In other words, if an apply_filters() call passes four total arguments, callbacks bound to it can accept none (the same as 1) of the arguments or up to four. The important part is that the $accepted_args value must reflect the number of arguments the bound callback actually opted to accept. If no arguments were accepted by the callback that is considered to be the same as accepting 1 argument. For example:
// Filter call. $value = apply_filters( 'hook', $value, $arg2, $arg3 ); // Accepting zero/one arguments. function example_callback() < . return 'some value'; >add_filter( 'hook', 'example_callback' ); // Where $priority is default 10, $accepted_args is default 1. // Accepting two arguments (three possible). function example_callback( $value, $arg2 ) < . return $maybe_modified_value; >add_filter( 'hook', 'example_callback', 10, 2 ); // Where $priority is 10, $accepted_args is 2.
Note: The function will return true whether or not the callback is valid. It is up to you to take care. This is done for optimization purposes, so everything is as quick as possible.
This function does not make any checks: whether there is an attached function or whether the function name is passed as a string, etc.. This is to make add_filter() work as fast as possible.
$hook_name(string) (required) The name of the filter to add the callback to. $callback(callable) (required) The callback to be run when the filter is applied. $priority(int) Used to specify the order in which the functions associated with a particular filter are executed. Lower numbers correspond with earlier execution, and functions with the same priority are executed in the order in which they were added to the filter. Default: 10 $accepted_args(int) The number of arguments the function accepts. Default: 1
Examples
#1 A common example that shows how you can add any label to the end of each article through the_content filter:
#2 Modify the «pictures signature» block (сaption)
Example of changing the caption of images ( ) for HTML 5. The function hooks on the img_caption_shortcode filter, which is responsible for converting the shortcode in the article content. To get all 3 parameters passed by the filter, specify the argument $accepted_args = 3 :
Don’t use an anonymous function as a callback function if you intend to use filter many times. Also, remember that it’s impossible to remove filter declared with an anonymous function.
$tag (строка) Название фильтра. $function_to_add Название функции, которая будет фильтровать значение переменной. Однако данная переменная позволяет задать не просто название функции строкой функция1 , то также и указать функцию внутри класса следующим образом array(‘Класс1’, ‘функция_внутри_класса1’) или, если всё это действо происходит внутри класса, то array(&$this, ‘функция_внутри_класса1’) , кроме того, если ваша версия PHP > 5.3.0, вы можете использовать анонимную функцию, как например:
Но я не рекомендую использовать такой прикольный способ, потому что если вдруг вам придётся сменить версию PHP на более низкую, то вы заколебетесь изменять всё это в своём коде.
И кстати, add_filter() не проверяет, существует ли указанная вами возвратная функция вообще. $priority (целое число) Приоритет выполнения, чем он меньше, тем раньше будет применена фильтрующая функция по отношению к другим фильтрующим функциям. $accepted_args (целое число) Общее количество переменных, которые будут переданы в фильтрующую функцию.
Возвращает true при успешном применении фильтрующей функции, иначе false
Примеры
Добавим произвольную строку в конце всех заголовков постов
Вряд ли это может вам понадобиться, но такой вот простой пример.
add_filter('the_title', 'misha_add_text_to_titles'); // если приоритет равен 10 и количество параметров - 1, то это значения по умолчанию и их в add_filter() можно не указыватьfunction misha_add_text_to_titles($title){$title = $title . "какой-то текст"; return$title; }
Множество других примеров на truemisha.ru
Также можете перейти на страницу метки functions.php на сайте и вашему вниманию предстанет огромное количество примеров, так или иначе связанных с применением фильтров или действий.
Миша
Впервые познакомился с WordPress в 2009 году. Организатор и спикер на конференциях WordCamp. Преподаватель в школе Нетология.
Пишите, если нужна помощь с сайтом или разработка с нуля.
Прикрепляет указанную PHP функцию к указанному хуку-фильтру. Так, во время срабатывания фильтра значение будет обработано указанной PHP функцией. Фильтры это, своего рода, зацепки внутри кода, через которые можно «отфильтровать» какие-либо данные. Например, в период получения и вывода текста на экран из базы данных, можно «на лету» изменить (отфильтровать) этот текст и вывести на экран уже измененный вариант текста. И благодаря фильтру для этого нам не придется редактировать функцию вывода в файлах движка, а можно подключиться к функции вывода через файл шаблона, использовав заранее предусмотренный разработчиками фильтр.
Функция не делает никаких проверок: существует ли прикрепляемая функция или передается ли название функции в виде строки и т.д.. Сделано это, чтобы add_filter() работала максимально быстро.
$tag(строка) (обязательный) Название фильтра, для которого будет срабатывать функция определенная в параметре $function_to_add. $function_to_add(строка) (обязательный) Название функции, которая будет срабатывать для указанного в предыдущем параметре фильтра. Название функции нужно указывать в виде строки: ‘название_функции’ . Для функций внутри классов указываем массив: array( ‘название_класса’, ‘название_функции’ ) . $priority(число) Приоритет выполнения функций для одного и тоже фильтра. Чем больше число, тем позднее будет выполнятся функция: например, сначала 10 потом 20. Функции с одинаковым приоритетом, будут выполнятся в порядке их добавления к массиву фильтров. По умолчанию: 10 $accepted_args(число) Количество аргументов передаваемых фильтром функции. Некоторые фильтры могут передавать больше чем 1 аргумент, допустим — 2, для таких случаев нужно указывать 2 в этом параметре. По умолчанию: 1
Примеры
#1 Внутри классов функцию фильтра нужно указывать через массив:
Помните, что невозможно удалить фильтр, объявленный анонимной функцией. Не используйте анонимную функцию в качестве коллбэк функции, если подразумевается многократное использование фильтра
При копировании статьи, ставьте обратную ссылку, пожалуйста!
"; return $out; >
#4 Изменения блока «подпись картинки» (сaption)
Пример изменения подписи у картинок ( [сaption] ) под стандарты HTML 5. Функция меняющая контент цепляется на фильтр img_caption_shortcode , который отвечает за преобразование шоткода [сaption] в контенте статьи. Чтобы получить все 3 параметра, передаваемые фильтром, укажем аргумент $accepted_args — 3: