Блоговод | Анатомия плагина WordPress. Часть 2.

Анатомия плагина WordPress. Часть 2.

wp plugin В первой части статьи мы говорили об actions и их применении. Пора поговорить о фильтрах (filters).

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

add_filter( 'comments_number', array( &$this, 'commentsNumber' ), 9999, 2);

1	add_filter( 'comments_number', array( &$this, 'commentsNumber' ), 9999, 2);

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

function comments_number( $zero = false, $one = false, $more = false, $deprecated = '' ) {
  global $id;
  $number = get_comments_number($id);
 
  if ( $number > 1 )
    $output = str_replace('%', number_format_i18n($number), ( false === $more ) ? __('% Comments') : $more);
  elseif ( $number == 0 )
    $output = ( false === $zero ) ? __('No Comments') : $zero;
  else // must be one
    $output = ( false === $one ) ? __('1 Comment') : $one;
 
  echo apply_filters('comments_number', $output, $number);
}

function comments_number( $zero = false, $one = false, $more = false, $deprecated = '' ) {

global $id;

$number = get_comments_number($id);

if ( $number > 1 )

$output = str_replace('%', number_format_i18n($number), ( false === $more ) ? __('% Comments') : $more);

elseif ( $number == 0 )

$output = ( false === $zero ) ? __('No Comments') : $zero;

else // must be one

$output = ( false === $one ) ? __('1 Comment') : $one;

echo apply_filters('comments_number', $output, $number);

}

Глядя на исходный код мы можем сделать следующие выводы:

функция может возвращать как простую строку, так и HTML-теги
в налагаемый фильтр передаётся два параметра: строка количества комментариев и количество комментариев в формате integer

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

Возвращаясь к используемой нами в конструкторе плагина функции add_filter, хочу описать что именно мы сделали (какие параметры использовали):

первый параметр – имя функции на которую накладываем фильтр
второй параметр – функция обработчик фильтра. Поскольку является методом класса мы не можем передать только имя обработчика, поэтому передаем в виде массива.
третий параметр – приоритет исполнения. Установив в значение 9999, пытаемся сделать так, чтобы наш фильтр, при наличие других фильтров для comments_number, выполнился последним.
четвёртый параметр – задаём количество входящих параметров. Как мы уже выяснили выше, параметров два, поэтому устанавливаем в 2.

В качестве обработчика фильтра мы задали метод класса нашего плагина commentsNumber, который собственно говоря и является ядром создаваемого (в данном случае) плагина. Поэтому перейдём к его рассмотрению.

function commentsNumber( $output, $number ) {
  $mcnOptions = $this->getOptions();
  $text = strip_tags( $output );
  $filterNeeded = !ctype_digit( $text ); 
 
  if ( $filterNeeded ) {
    switch ( $number ) {
      case 0: $mcnOutput = str_replace( $text, $mcnOptions['commentStringZero'], $output );
      break;
 
      case 1: $mcnOutput = str_replace( $text, $mcnOptions['commentStringOne'], $output );
      break;
 
      default: $mcnOutput = str_replace( $text, sprintf( __ngettext( "%d Comment", "%d Comments", $number, "multilingual-comments-number" ), $number ), $output );
      break;
    }
    echo $mcnOutput;
  } else echo $output;
}

function commentsNumber( $output, $number ) {

$mcnOptions = $this->getOptions();

$text = strip_tags( $output );

$filterNeeded = !ctype_digit( $text );

if ( $filterNeeded ) {

switch ( $number ) {

case 0: $mcnOutput = str_replace( $text, $mcnOptions['commentStringZero'], $output );

break;

case 1: $mcnOutput = str_replace( $text, $mcnOptions['commentStringOne'], $output );

break;

default: $mcnOutput = str_replace( $text, sprintf( __ngettext( "%d Comment", "%d Comments", $number, "multilingual-comments-number" ), $number ), $output );

break;

}

echo $mcnOutput;

} else echo $output;

}

Первым делом получаем заданные пользователем параметры плагина (об этом поговорим чуть позже).

Затем в переменную $text записываем значение входящей строки количества комментариев, убрав из неё все HTML-теги. Таким образом мы получаем только строку количества комментариев и ничего более.

Проверяем полученную строку количества комментариев на наличие в ней буквенных литер. Если ДА – строка содержит слова и требуется фильтрация, если НЕТ – фильтрация не требуется, т.к. мы имеем дело с передачей строки количества комментариев в виде строки цифр, не требуещей перевода.

Если фильтрация требуется, формируем собственную строку вывода, если нет, возвращаем полученную строку количества комментариев КАК ЕСТЬ.

При формировании строки вывода мы используем полученные параметры, заданные пользователем для количества комментариев равных 0 и 1 (кто-то любит писать “Нет комментариев”, а кто-то “Оставьте комментарий”). Во всех остальных случаях мы используем возможности PHP GetText применяя конструкцию __ngettext – sprintf. Для правильного употребления форм множественного числа в локализованных версиях, команда разработчиков WordPress рекомендует использовать именно эту конструкцию.

Естественно, заменяя во входящей строке количества комментариев только ту часть которая не является HTML-тегами, то что мы экстрактировали в переменную $text, мы полностью сохраняем оригинальные HTML-теги. Для чего это нужно? Это не только желание получить валидный код, но и насущная необходимость. Вот пример использования плагина не сохраняющего HTML-теги (не буду говорить какого) и пример вывода с помощью Multilingual Comments Number на странице редактирования комментариев: