WordPress add filter


add_filter() является вспомогательной функцией apply_filters(). Прежде чем apply_filters будет запущен для определенного фильтра (аргумент $tag в add_filter()), вы можете использовать add_filter для регистрации фильтра для тега. Когда apply_filters() выполняется с этим именем тега, он вызывает все зарегистрированные фильтры в порядке. Фильтры используются для передачи данных через функции манипуляции. Например, я часто использую фильтр wp_list_pages. Я использую его для удаления разрывов строк из списка страниц. Итак, как это работает:

Сначала я определяю функцию, которая принимает один параметр и возвращает его после работы с ним:

function my_list_pages_filter($pages){  $pages = preg_replace( array("n","r"), '', $pages );  return $pages; } 

Затем я добавляю крючок фильтра: add_filter (‘wp_list_pages’, ‘my_list_pages_filter’);

add_filter


сообщает WordPress «Когда вызывается функция apply_filters с первым аргументом» wp_list_pages «, вызовите my_list_pages_filter«. Фильтры должны отправлять хотя бы одно значение (любого типа: string, array, integer и т.д.), И они ожидают, что функция вернет одно значение.

Они предоставляют вам способ управления вводом перед отправкой.

do_action — совершенно другой крючок. Чтобы отправить информацию в вашу функцию фильтра, сделайте следующее (взятое из вашего примера):

<div id="content" <?php $class='post post_content'; echo apply_filters('my_custom_classes', $class); ?>> 

И затем в файле functions.php добавьте следующее:

add_filter('my_custom_classes','my_custom_classes_function'); function my_custom_classes_function($classes){  $output 'class="'. $classes.'"';  return $output; } 

Это довольно рудиментарное использование фильтров, но это начало. Вы действительно можете понять, что вы можете сделать с фильтрами с тем же примером с некоторыми улучшениями:

function my_custom_classes_function($classes){  $classes = explode( ' ', $classes );  if(is_home())  $classes[] = 'home_content';  if(is_single())  $classes[] = 'single_content';  if(is_page())  $classes[] = 'page_content';  if(is_tag())  $classes[] = 'tag_content';  $output 'class="'. implode( ' ', $classes ) .'"';  return $output; }   

qaru.site

Что такое WordPress — фильтр

В Кодексе WordPress фильтрам дано следующее определение:

Итак, фильтр это функция на php, которая записывается в стек вызовов встроенной системы фильтров WordPress. Но в себе она может содержать сторонние функции и другие конструкции. Фильтр является одним из двух видов хуков (hooks) в WordPress. Второй — действие (action), но это предмет для другой серии статей.

Возможно, эта тема покажется вам сложной, но фильтры (как и действия) очень легко понять. Вначале моего знакомства с этими понятиями мне самому показалось все довольно сложным и запутанным, но, увидев, насколько они просты, я познакомился с сотнями фильтров и действий, просто изучая кодекс WordPress или копаясь в исходном коде. Определенно, вам также стоит узнать о сотнях фильтров. Но для начала вы должны научиться их использовать.

Используем фильтры в WordPress

Использовать фильтры в WordPress, как я уже сказал, довольно легко. Некоторые основные функции стоит выучить и узнать о том, что делает каждый фильтр. Стоит признать, что довольно тяжело выучить функционал всех фильтров сразу, но этого и не стоит делать. Вы познакомитесь с ними в процессе работы, по мере необходимости.

В этой статье мы собираемся проделать четыре вещи:

  • Создадим функцию фильтра;
  • Сделать из нее хук;
  • Убрать функцию из фильтра;
  • Создать свой собственный фильтр.

Создаем функцию и прикрепляем ее к фильтру

Для того чтобы поиграть с данными, которые мы получим из фильтра, необходимо создать функцию, которая определит, какие действия она будет выполнять с данными и затем подключить ее к фильтру.

Давайте предположим, что мы будем писать плагин для удаления гласных в заголовках публикаций. Вместо того чтобы писать «удалить гласные в моих постах», мы пишем «подключить функцию удаление гласных из заголовков моих публикаций к фильтру».

Сложно? На самом деле, нет. В приведенном ниже примере, мы напишем код функции, которая удаляет гласные во всем тексте:

Функция берет строку заголовка $title, удаляет гласные и возвращает строку. Довольно просто, верно? Теперь прыгнем на уровень выше, сделаем хук, и прицепим его к фильтру:

Заметили новую функцию? Взглянем на add_filter():

  • $tag (обязательный параметр) – имя фильтра;
  • $function_to_add (обязательный параметр) – имя функции для хука;
  • $priority (опция) – Целое число для определения момента исполнения функции. По умолчанию равно 10: Функция сработает раньше, если вы снизите значение, и позже, если вы повысите его;
  • $accepted_args (опция) — Значение, нужное чтобы определить количество аргументов, которые пропускает фильтр. Значение по умолчанию равно1.

Удаляем фильтр

Конечно же, мы также можем убрать функцию, прикрепленную к фильтру. Для этого используем функцию remove_filter(). И смотрим, как она работает:

Параметры такие же, как и в случае с add_filter():

  • $tag (обязательный параметр) – имя фильтра;
  • $function_to_remove (обязательный параметр) – имя функции для удаления;
  • $priority (опция) — приоритет функции (определено при первом подключении функции).

Еще одна функция, remove_all_filters(), у которой всего лишь два параметра ($tag и $priority), в которых указываются имя функции и приоритет. Имя функции говорит само за себя. Она отключает все функции, прицепленные к фильтру.

Создаем свой собственный фильтр

Хотите знать, как создаются фильтры? Для этого существует специальная функция apply_filters(), находящаяся в ядре. Конечно же, ее можно использовать и вне ядра, и это означает то, что мы можем создавать фильтры внутри наших плагинов.
Посмотрим, как это работает на практике:

  • $tag (обязательный параметр) – имя привязываемой функции;
  • $value (обязательный параметр) — значение, которое будет меняться функцией, подключенной к фильтру через add_filter();
  • $var1, $var2 и так далее (опционально) – параметры фильтра (столько, сколько потребуется). Функция фильтра может использовать эти параметры, но они не смогут быть возвращены функциями.

Подумаем над таким примером: Представьте, что вы пишите функцию, которая возвращает только известную цитату Питера Гриффина:

Если вы хотите дать возможность пользователю отфильтровать эту цитату (не трогая код вашего плагина), вам нужно использовать функцию apply_filters() следующим образом:

Таким образом, другой разработчик сможет использовать ваш плагин и обработать данные вашей функции как в этом примере:

Теперь, каждый раз, когда будет вызвана функция peter_griffin_quote(), цитата Питера будет слегка видоизменяться, при этом код плагина останется неизменным. Отлично!

Заключение

Чем больше вы работаете с фильтрами, тем веселее идут дела. Есть сотни фильтров, и, изучая их, вы каждый раз подходите на один шаг ближе к тому, чтобы стать WordPress — гуру. В следующей части этой серии статей мы собираемся рассказать о 10 WordPress — фильтрах:

  • login_errors;
  • comment_post_redirect;
  • allowed_redirect_hosts;
  • body_class;
  • locale;
  • sanitize_user;
  • the_content;
  • the_password_form;
  • the_terms;
  • wp_mail_from.

Мне не терпится приступить к написанию следующей статьи из этой серии, и я надеюсь, что она окажется полезна вам, так же, как и мне. Если вы думаете, что сможете помочь мне с уроками, предлагая другие фильтры или примеры, не стесняйтесь, поделитесь своими мыслями в комментариях.

И если вам понравилось то, что вы читаете в этой статье, не забудьте поделиться ею!


Увидимся на следующем уроке!

Перевод статьи “50 Filters of WordPress: An Introduction to Filters” был подготовлен дружной командой проекта Сайтостроение от А до Я.

www.internet-technologies.ru

Hook a function or method to a specific filter action.

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.

wpseek.com

Помимо добавления функциональности или контента, часто нужно работать с контентом иным образом. Например модифицировать или удалять его частично или полностью перед тем тем как он будет показан пользователю на странице. Данную возможность в WordPress предоставляют так называемые filter хуки. filter хуки — это второй тип хуков в WordPress. Напомню, что нам уже известен один вид хуков: action. В этом рецепте мы напишем плагин, который будет использовать filter хук для модификации заголовков страниц, а конкретно он будет добавлять к заголовку текущей страницы тип контента этой самой страницы.


  1. Перейдите в каталог плагинов WordPress: wp-content/plugins
  2. Создайте новую директорию для плагина под названием title-filter
  3. Зайдите в директорию плагина и создайте php-файл: title-filter.php
  4. Откройте ваш новый файл в текстовом редакторе и добавьте необходимый комментарий-заголовок назвав плагин «Title Filter»
     <?php /*  Plugin Name: Title Filter  Plugin URI:  Description: Page Title Filter  Version: 1.0  Author: Somebody  Author URI: http://xxxxxx.xx/  License: GPLv2 */  

  5. Добавьте следующую строку кода, которая прикрепит функцию к хуку wp_title, который выполняется когда WordPress подготавливает заголовок страницы (title) перед выводом его в тег head страницы:
      add_filter( 'wp_title', 'title_filter' ); 

  6. Далее добавим реализацию прикрепленной callback-функции:
     function title_filter( $title ) {  // Установим в заголовок тип контента  if ( is_front_page() )  $new_title = 'Front Page >> ';  elseif ( get_post_type() == 'page' )  $new_title = 'Page >> ';  elseif ( get_post_type() == 'post' )  $new_title = 'Post >> ';   if ( isset( $new_title ) ) {  return $new_title . $title;  }   return $title; } 

  7. Сохраняем файл
  8. Идем в админку нашего сайта во вкладку Plugins
  9. Находим наш плагин в списке и активируем его

Если вы все сделали правильно, то увидите что ваши заголовки страниц приняли вид: ТИП >> ЗАГОЛОВОК

Как это работает…

Функция add_filter используется для того что бы вы могли подцеплять к хукам типа filter свои callback-функции. Хуки типа filter позволяют плагинам изменять, дополнять, удалять или полностью менять данные в процессе их подготовки WordPress — ом перед тем как он отдаст их пользователю. Для этого в callback-функции хуков фильтров должны принимать аргумент — данные с которыми нужно будет что-то сделать.

Про функции filter-хуков удобно думать так как будто это действительно некие фильтры в которые втекают и вытекают данные, с которыми в этих фильтрах что то происходит.

В отличии от callback-функций action — хуков в callback-функциях filter-хуков желательно воздержаться от непосредственно вывода данных в поток при помощи инструкция типа print, echo и т.п. т.к. работа этих функций происходит до того момента как содержимое будет полностью готово для отправки пользователю то результаты могут быть непредсказуемы и ожидаемая строка, которую вы выведете с помощью echo например, в итоге может оказаться где угодно на странице. Вместо этого callback-функции filter-хуков обязаны вернуть результат своей работы при помощи инструкции return.

При более детальном взгляде можно заметить сходство функции add_filter с уже знакомой нам функцией add_action, с которой мы познакомились ранее:


 add_filter( $hook_name, $your_function_name, [$priority], [$accepted_args] ); 

Первый параметр — это строка, имя хука, к которому привяжется пользовательская функция. Это имя нужно постараться написать без ошибок; в противном случае наша функция не будет вываться, и к тому же мы не увидим никакого сообщения об ошибке — помните об этом факте.

Вторым параметром является имя callback-функции, которая будет вызываться при инициализации хука. Эта функция может иметь любое имя, с единственным условием — оно должно быть уникальным, чтобы избежать коллизий с именами функций из других плагинов, или из кода WordPress. В этом рецепте имя функции строится из имени плагина, что делает его более-менее уникальным.

Параметр priority является необязательным (заключен в квадратные скобки) и имеет значение по умолчанию — 10. Это приоритет выполнения привязанной callback-функции относительно других функций, привязанных к этому же хуку.

В любом плагине можно зарегистрировать одну или более callback-функции на нужный filter hook, с помощью функции add_filter. Функции навешенные на один и тот же хук ставятся в очередь. Так вот параметр priority — делает эту очередь приоритетной.

Если вам нужно, чтобы ваша функция вызывалась до или после других функций, навешенных на этот же хук — измените значение параметра priority.

Последний параметр: accepted_args, имеет значение по умолчанию 1. Ему всегда должно быть присвоено число. Этот параметр устанавливает число аргументов, которые будут переданы привязанной callback-функции. Если вы будете использовать фильтры, которые передают много параметров в callback-функции, то вы должны явно указать их число в этом параметре.

Помимо демонстрации того как изменить заголовок страницы этот наш плагин так же демонстрирует как можно использовать некоторые WordPress функции-условия и WordPres функции-запросы.

Функция is_front_page очень удобна, когда нужно сделать так что бы код выполнялся только на фронтенде, но не в админке (или наоборот с инвертированием результата). Эта функция вернет Boolean true или false и её очень удобно использовать в операторах-условиях.

Помимо posts, pages и пользовательских типов постов, WordPress может отображать множество информации на сайте. Для создания плагинов, которые будут адаптироваться ко всем этим типам контента, функция get_post_type может быть очень удобна, она возвращает тип WordPress поста.

Так же по аналогии с функцией do_action для action хуков, для filter хуков так же существует функция явного вызова на выполнение всех прикрепленных хуку функций это функция : apply_filters

 apply_filters( $tag, $value, $var ... ); 

Данный функционал так же по аналогии с функцией do_action позволит вам использовать свои собственные типы фильтров и инициировать их выполнение тогда, когда вам это потребуется.

Предыдущие статьи этого цикла:

  1. WordPress: С чего начинаются плагины
  2. WordPress: Добавление контента в тег head страниц
  3. WordPress: Функции для работы с путями

php-zametki.ru

What do we need WordPress filters for?

But what does all this mean in the practical world, and how can we use and take advantage of WordPress filters? We´ll see it with the aid of some examples.

WordPress filters do their work somewhere between the database and the browser, or just the other way around, depending on what the WordPress code is doing at any particular moment.

For instance, when the user is searching a blog, WordPress retrieves the applicable posts from the database and, among other things, it filters the content of each post to truncate its length and to add the “read more…” link before sending it to the screen to display the archive page. In cases like this you could think of the job done by the filter as “last minute” editing.

WordPress filters can be used for a wide variety of applications. Just to name a few of them, we could use WordPress filters to achieve any the following:

  • Add specific html to particular pieces of data.
  • Change the formatting of text.
  • Add elements to content.
  • Modify the way any part of the WordPress data is displayed.

For example, que might want to wrap the post title inside a div with a particular CSS class, or add a background to the post excerpts on a blog page, or add a notice at the beginning or end of a post whenever a certain condition is met. All that (and much, much more) can be done by means of WordPress filters.

The add_filter function

So WordPress filters intercept the piece of data to be modified and alter it the way we want. What we use to intercept the right data in the right moment is actually the hook itself. It´s the $tag variable in the add_filter function, which in its simplest form looks like this:

add_filter( $tag, $function_to_add );

The add_filter function is what we´ll use in order to bind a filtering function ($function_to_add, usually referred to as “callback function” or just “filter function”) to a particular filter hook ($tag).

The callback or filter function needs to be fed with the unmodified data (for example, the content of a post) and it must return the modified (filtered) data.

So, if for example we were to filter the post content by adding to every post on our blog that belongs to the “tutorials” category a final paragraph in italics saying “I hope you like this tutorial, please let me know through the comments”, our filter function would look like this:

So our function takes the post content retrieved from the database (which resides in the variable $content) and, in case the post belongs to the tutorials category, adds the desired paragraph to it. If it doesn´t, the function just returns the unmodified content (because the if condition is not met). But our function must return the data (the post content, in our case) anyway, whether it is filtered or unmodified, for the rest of the WordPress code to use it. This also means that a particular piece of data can be filtered as many times as we want or require.

Once we have such a function defined in the functions.php file of our child theme, all we need to do is to bind it to the appropriate hook. The way to hook our new function is, as we´ve just seen, the add_filter function.

We just need to add a new line of code to our child theme´s functions.php file hooking our custom filter function to the appropriate hook.

In our example we want to modify the content of some posts, so we´ll bind our function to the the_content hook. According to the WordPress Codex: the “the_content” filter is used to filter the content of the post after it is retrieved from the database and before it is printed to the screen.

So these are the lines we´ll need to add to the functions.php file of our child theme:

On the code above I´ve changed the name of the callback function to something more significant than “function_to_add”, if you noticed. Other than that, the only addition to what we had before is the add_filter line, where we´re hooking our function to the “the_content” filter hook.

Now it is time to check whether those few lines of code we´ve added to our child theme work or not.

I´ve pasted those lines on the functions.php file of a child theme of Twenty Sixteen on a local dev site, and then published a couple of sample posts, one of them having the Tutorials category.

Here we have the results. This is the post with the Tutorials category:
worpress-filters-example-1

However, my Lorem Ipsum post does not belong to the Tutorials category, and therefore this other post doesn´t get the final paragraph we´ve just added for tutorials:

worpress-filters-example-2

Wow, that was simple, wasn´t it? Imagine all you can achieve with WordPress filters!

By the way, when I talked before about the simplest form of the add_filter function it was because this function can accept the use of optional arguments and it can also handle optional priorities (as it also happens with the add_action function in the case of action hooks, as we saw in the previous post of this series), its general form being like this, for your information:

add_filter( $tag, $function_to_add, $priority, $accepted_args );

For any other example of application you might think of, you can select your appropriate filter by means of the Filter Reference page on the WordPress Codex.

Why WordPress filters work

At different places of the WordPress core code (or of your parent theme code, for instance), a function named apply_filters is called. It is used to create a new filter hook:

apply_filters( $tag, $value );

When that point of the code is reached, every filtering callback function bound to that particular hook will be executed, so the piece of data contained in $value (the value on which the filters hooked to $tag are applied on) will be modified by the functions that were hooked via the add_filter function.

www.wpthemedetector.com

Примеры

Добавим произвольную строку в конце всех заголовков постов

Вряд ли это может вам понадобиться, но такой вот простой пример.

Множество других примеров на truemisha.ru

Прежде всего я рекомендую вам почитать полное руководство по фильтрам в WordPress.

Также можете перейти на страницу метки functions.php на сайте и вашему вниманию предстанет огромное количество примеров, так или иначе связанных с применением фильтров или действий.

misha.blog

События

События или действия (actions) в WordPress очень похожи на события в JavaScript. Событие выполняется вызовом функции do_action(), а добавить функцию к любому событию можно с помощью функции add_action().

При выполнении события или действия, выполняются все функции, добавленные к событию в определенном порядке. Это легче всего понять с помощью простого примера. Определяем три функции, которые будут выводить 1, 2 и 3 соответственно:

function one() { echo 1; }  function two() { echo 2; }  function three() { echo 3; }  

Добавляем функции к событию foo с помощью функции add_action():

add_action( 'foo', 'one' );  add_action( 'foo', 'two' );  add_action( 'foo', 'three' );  

И выполняем наше событие с помощью функции do_action():

do_action( 'foo' ); // выведет 123  

Первый аргумент к функциям — это строка foo — название события. Название может быть любым, но во избежание конфликтов с другими плагинами и темами в собственных событиях лучше использовать префикс, например myplugin_foo, где myplugin это название вашего плагина.

Второй аргумент к функции add_action() — это функция, которая вызывается в момент выполнения события. Функции в рамках одного события выполняются в том же порядке, в котором они были добавлены к событию, за исключением когда функция добавляется к событию с повышенным или пониженным приоритетом. О приоритетах чуть позже.

Итак, наш пример вызовет функции one(), two() и three() по порядку, что выведет на экран 123. Конечно мы могли самостоятельно вызвать эти функции в этом же порядке на месте do_action(), что дало бы тот же самый результат. Так зачем использовать события?

Зачем использовать события

Любой другой плагин или тема смогут легко добавить или удалить функции из вашего события без необходимости изменять код вашего плагина. Такой подход делает ваш плагин более гибким. Например:

/* В другом плагине */  function four() { echo 4; }    remove_action( 'foo', 'three' );  add_action( 'foo', 'four' );  

Таким образом, когда дело дойдет до вызова события foo в вашем плагине, на экран выведется уже не 123, а 124, поскольку другой плагин удалил функцию three() из вашего события с помощью функции remove_action(), и добавил на ее место новую функцию four().

Пример с выводом чисел не самый полезный. На практике достаточно легко придумать события в вашей теме или в плагине, которые могли бы быть полезными для других плагинов, например:

  • Ваша тема может выполнить событие в момент вывода шапки, и любой плагин сможет вывести на этом месте баннер, не изменяя код вашей темы
  • Ваша тема может выполнить событие в подвале, и с помощью плагина можно будет вставить в подвал любой текст
  • Ваш плагин выводит блок «поделиться» в конце каждой статьи, другой плагин сможет добавить новую социальную сеть в этот же блок

Стоит так же отметить, что в самом ядре WordPress есть более 1500 фильтров и событий, которые можно использовать в темах и плагинах.

Фильтры

Фильтры в WordPress очень похожи на события. Главным отличием является то, что у фильтров есть значение, которое они передают каждой привязанной функции, соответственно каждая функция должна вернуть это же или измененное значение. Рассмотрим простой пример:

function plus_one( $value ) {   $value = $value + 1;   return $value;  }  

Эта функция принимает один аргумент, добавляет к нему единицу и возвращает результат. Добавим нашу функцию к новому фильтру с помощью add_filter():

add_filter( 'foo', 'plus_one' );  

Теперь все функции добавленные к фильтру foo (в нашем случае это всего одна функция) можно легко вызвать или «применить» с помощью функции apply_filters():

echo apply_filters( 'foo', 5 ); // 6  

В функцию apply_filters() вторым аргументом мы передаем фильтруемое значение. Оно может быть любым и оно будет передаваться каждой функции привязанной к фильтру, при этом любой фильтр может это значение изменить.

В данном случае на экран выведется значение 6, поскольку значение 5 было пропущено через функцию plus_one(), которая изменила оригинальную переменную. Если убрать функцию у фильтра с помощью remove_filter(), то наш код выведет первоначальное значение 5:

remove_filter( 'foo', 'plus_one' );  echo apply_filters( 'foo', 5 ); // 5  

Так же как и события, функции к фильтрам могут добавляться в любом другом плагине или в теме, и выполняются эти функции в том порядке, в котором они были добавлены к фильтру, за исключением повышенного или пониженного приоритетов.

Пример хорошего фильтра

Рассмотрим более интересный пример: создадим массив, который будет содержать ссылки на наши профили в социальных сетях и выводить эти ссылки в шапке нашей темы WordPress. В functions.php:

function get_my_social_profiles() {   $profiles = array(   'twitter' => 'http://twitter.com/wpmagru',   'facebook' => 'http://facebook.com/wpmagru',   );   return $profiles;  }

Возвращаемый массив можно использовать в цикле в нашем файле header.php:

$profiles = get_my_social_profiles();  foreach ( $profiles as $service => $url ) {   printf( '<a href="%s">%s</a>', esc_url( $url ), $service );  }  

Данный код выведет ссылки на Twitter и Facebook в шапке нашей темы. Для того чтобы добавить новую ссылку в список, нам придется изменять саму тему, или же создать новый фильтр в функции get_my_social_profiles():

/* В functions.php */  function get_my_social_profiles() {   $profiles = array(   'twitter' => 'http://twitter.com/wpmagru',   'facebook' => 'http://facebook.com/wpmagru',   );   return apply_filters( 'my_social_profiles', $profiles );  }

Таким образом любой плагин или дочерняя тема смогут легко управлять списком социальных профилей, не трогая оригинальную тему. Например, убрать ссылку на Twitter и добавить ссылку на Google+ можно с помощью следующего кода в плагине:

function change_my_social_profiles( $profiles ) {   unset( $profiles['twitter'] );   $profiles['google-plus'] = 'https://plus.google.com/+wpmagru';   return $profiles;  }  add_filter( 'my_social_profiles', 'change_my_social_profiles' );  

Фильтры и события в ядре WordPress

Как мы уже упомянули, в WordPress есть более 2000 фильтров и событий, которыми можно воспользоваться в плагинах или темах для того, чтобы изменить поведение ядра. Рассмотрим несколько интересных примеров.

Отключить комментирование

Отключить комментирование на всем сайте, на зависимо от настроек в параметрах можно с помощью следующего кода:

function my_comments_open() { return false; }  add_filter( 'comments_open', 'my_comments_open' );  

Фильтр comments_open используется в ядре WordPress каждый раз для того, чтобы проверить открыты ли комментарии к той или иной статье. Наша функция всегда возвращает значение false для этого фильтра, поэтому комментарии будут закрыты везде.

Кстати, ядро WordPress определяет несколько вспомогательных функций для работы с подобными фильтрами:

  • __return_true() — возвращает true
  • __return_false() — возвращает false
  • __return_zero() — возвращает 0
  • __return_empty_string() — возвращает пустую строку
  • __return_empty_array() — возвращает пустой массив
  • __return_null() — возвращает null

То есть наш фильтр на comments_open можно переписать в одну строку:

add_filter( 'comments_open', '__return_false' );  

Изменить длину автоматических цитат

За длину автоматических цитат отвечает фильтр excerpt_length:

function my_excerpt_length( $length ) {   $length = 10;   return $length;  }  add_filter( 'excerpt_length', 'my_excerpt_length' );  

С помощью фильтра excerpt_more можно изменить текст, который который ставится в конце автоматический цитаты, по умолчанию это [...]:

function my_excerpt_more( $more ) {   $more = '&rarr;';   return $more  }  add_filter( 'excerpt_more', 'my_excerpt_more' );  

Добавить баннер к содержимому каждой статьи

Фильтр the_content выполняется перед выводом содержимого каждой статьи. Через фильтр проходит само содержимое статьи, поэтому в него легко добавить баннер «на лету» с помощью плагина:

function my_banner( $content ) {   $banner = '<a href="#"><img src="..." /></a>';   $content = $banner . $content;   return $content;  }  add_filter( 'the_content', 'my_banner' );  

Добавить favicon.ico в раздел <head>

В разделе <head> в каждой теме выполняется событие wp_head. Во время этого события можно вывести ссылку на файл favicon.ico, вставить произвольный код JavaScript или CSS и многое другое:

function my_favicon() {   echo '<link rel="shortcut icon" href="http://example.org/favicon.ico" />';  }  add_action( 'wp_head', 'my_favicon' );  

Учтите, что если вам необходимо подключить внешние .js или .css файлы, делать это стоит с помощью функций wp_enqueue_script() и wp_enqueue_style() во время события wp_enqueue_scripts, а не напрямую в wp_head.

В каждой версии WordPress добавляются все больше и больше новых и полезных фильтров и событий. Список большинства фильтров и событий в ядре можно посмотреть на сайте Адама Брауна, или просканировав файлы ядра на «do_action» и «apply_filters».

Приоритеты

Функции добавленные к фильтрам и событиям выполняются в том же порядке, в котором они были добавлены, но порядок легко изменить с помощью приоритетов. Приоритет указывается третьим аргументом к функциям add_action() и add_filter().

Без указания этого аргумента функции к фильтрам и событиям добавляются по умолчанию с приоритетом 10. Функции выполняются от меньшего приоритета к большему, т.е. чем меньше приоритет, тем раньше выполняется функция.

Вернемся к примеру с цифрами:

add_action( 'foo', 'one' );  add_action( 'foo', 'two' );  add_action( 'foo', 'three' );    do_action( 'foo' ); // выведет 123  

Если изменить приоритет выполнения функции three() на 9, то она выполнится раньше остальных:

add_action( 'foo', 'one' );  add_action( 'foo', 'two' );  add_action( 'foo', 'three', 9 );    do_action( 'foo' ); // выведет 312  

Подобным образом, указав приоритет 11 для функции one(), она выполнится позднее всех остальных, несмотря на то, что она была добавлена первой с помощью add_action():

add_action( 'foo', 'one', 11 );  add_action( 'foo', 'two' );  add_action( 'foo', 'three', 9 );    do_action( 'foo' ); // выведет 321  

Дополнительные параметры

В каждую функцию, привязанную к фильтру или событию, легко передать дополнительные параметры. Делается это при вызове функций do_action() или apply_filters(), например:

do_action( 'foo', $arg1, $arg2, $arg3 );  $value = apply_filters( 'foo', $value, $arg1, $arg2, $arg3 );  

Ключевым моментом является то, что при добавлении функции к фильтру или событию нам необходимо указать количество принимаемых аргументов, за это отвечает четвертый параметр функций add_action() и add_filter().

Например, если в функции к событию foo мы хотим принять все три аргумента, необходимо указать 3 в качестве четвертого параметра к add_action():

function my_func( $arg1, $arg2, $arg3 ) { ... }  add_action( 'foo', 'my_func', 10, 3 );  

Подобным образом, если в функции добавленной к фильтру мы хотим принять только $arg1 в качестве дополнительного аргумента, то просим add_filter() передать всего два аргумента — первый аргумент $value, и второй дополнительный аргумент $arg1:

function my_func( $value, $arg1 ) { ... }  add_filter( 'foo', 'my_func', 10, 2 );  

Пример

Хорошим примером передачи дополнительных аргументов является фильтр allow_password_reset, с помощью которого можно запретить сброс пароля для пользователей:

add_filter( 'allow_password_reset', '__return_false' );  

Это запретит сброс пароля для всех пользователей на сайте, но если нам необходимо запретить сброс пароля только супер-администраторам в сети мультисайт (в целях безопасности), мы можем воспользоваться дополнительным аргументом:

function my_filter( $allow, $user_id ) {   if ( is_super_admin( $user_id ) )   $allow = false;     return $allow;  }  add_filter( 'allow_password_reset', 'my_filter', 10, 2 );  

Учтите, что функции привязанные к фильтрам могут изменять только первый аргумент, передаваемый в фильтр. То есть функция приведенная выше может изменить только аргумент $allow, но не $user_id.

Для того, чтобы дать функциям возможно изменять более одного передаваемого аргумента, фильтры (и события) могут воспользоваться передачей переменных и объектов по ссылке в PHP, как это делает например событие pre_get_posts.

ООП, классы, объекты и анонимные функции

Разработчики тем и плагинов WordPress часто предпочитают объектно-ориентированный стиль программирования, где большая часть кода выполняется внутри объекта, а не в глобальном пространстве. Если функциям add_action() и add_filter() необходимо передать не функцию для вызова, а метод объекта, его необходимо передать в специальном формате массивом:

class My_Class {   function __construct() {   add_filter( 'the_content', array( $this, 'filter_content' ) );   }     function filter_content( $content ) {   // ...   return $content;   }  }  new My_Class();  

Похожим образом можно передать статический метод класса:

add_filter( 'the_content', array( 'My_Class', 'filter_content' ) );  add_filter( 'the_content', 'My_Class::filter_content' ); // PHP >= 5.2.3  

Фильтры и события поддерживают и анонимные функции, например:

add_filter( 'the_content', create_function( '$content', 'return $content;' ) );  add_filter( 'the_content', function( $content ) { return $content; } ); // PHP >= 5.3  

Пользоваться анонимными функциями с фильтрами и событиями в WordPress мы не рекомендуем, поскольку их сложно отлаживать (например с помощью плагина Debug Bar Slow Actions) а функция create_function() не кэшируется на уровне байт-кода, например в APC.

Заключение

Фильтры и события лежат в основе самого WordPress, и работу с ними следует освоить каждому разработчику тем и плагинов, ведь именно фильтры и события позволяют расширять ядро популярной системы.

Разработчикам тем и плагинов для WordPress так же не следует забывать о фильтрах и событиях внутри их собственных продуктов для того, чтобы делать их более модульными, гибкими и легко изменяемыми с помощью стороннего кода.

Если у вас возникнут вопросы о фильтрах и событиях в WordPress, оставьте комментарий и мы обязательно вам ответим.

wpmag.ru


You May Also Like

About the Author: admind

Добавить комментарий

Ваш e-mail не будет опубликован. Обязательные поля помечены *

Этот сайт использует Akismet для борьбы со спамом. Узнайте как обрабатываются ваши данные комментариев.