8.3. Инстанцирование фильтра

В Zend Framework 3 фильтр можно создать несколькими способами:

• инстанцировать его вручную (с помощью оператора new);
• создать его с помощью класса фабрики (передав описание в виде массива), этот способ чаще всего используется при добавлении в форму правил фильтрации и валидации; и
• инстанцировать его неявно с помощью класса-обертки StaticFilter.

Далее мы рассмотрим эти три способа более детально.

8.3.1. Способ 1: Инстанцирование фильтра вручную

Как мы уже сказали, фильтр, в целом, можно использовать не только с формами, но и для фильтрации произвольных данных. Чтобы это сделать, просто создайте экземпляр класса фильтра, настройте фильтр с помощью предоставляемых им методов и вызовите метод filter().

Рассмотрим, например, использование фильтра StringTrim, который убирает пробелы из начала и из конца строки.

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

Методы, представленные этим фильтром, перечислены в таблице 8.2:

Как видите из таблицы выше, фильтр StringTrim, вдобавок к методу filter(), предоставляет метод конструктора, которому вы можете при желании передать полный список опций для инициализации фильтра, и методы setCharList() и getCharList(), которые могут быть использованы для задания указанных опций фильтра.

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

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

Пример 1. Передача опций методу конструктора.

<?php
// Определяем псевдоним для имени класса фильтра (опционально).
use Zend\Filter\StringTrim;

// Создаем экземпляр фильтра, передавая опции конструктору.
$filter = new StringTrim(['charlist'=>"\r\n\t "]);

// Выполняем операцию удаления пробелов из начала и конца строки.
$filteredValue = $filter->filter(' name@example.com  ');

// Ожидаемый вывод фильтра - строка 'name@example.com'.

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

В строке 9 мы вызываем метод filter() и передаем ему строковое значение " name@example.com ", из которого хотим убрать пробелы. Ожидаемый результат этого вызова - строка "name@example.com".

Пример 2. Без передачи опций конструктору.

<?php
// Определяем псевдоним для имени класса фильтра (опционально).
use Zend\Filter\StringTrim;

// Создаем экземпляр фильтра.
$filter = new StringTrim();

// Указываем, какие символы надо удалять.
$filter->setCharList("\r\n\t ");

// Выполняем операцию удаления пробелов из начала и конца строки.
$filteredValue = $filter->filter(' name@example.com  ');

// Ожидаемый вывод фильтра - строка 'name@example.com'.

Во фрагменте выше мы создаем объект фильтра StringTrim с помощью оператора new (строка 6).

В строке 9, мы (опционально) вызываем метод setCharList() фильтра StringTrim для задания списка символов, которые фильтр будет удалять (в нашем примере мы сообщаем фильтру, что нужно удалять символы перевода строки, символы табуляции и пробелы). Вызывать этот метод необязательно, так как у фильтра уже есть стандартный список символов, которые нужно убирать.

Наконец, в строке 12 мы вызываем метод filter() и передаем ему строковое значение " name@example.com ", из которого хотим убрать пробелы. Ожидаемый результат этого вызова - строка "name@example.com".

8.3.2. Способ 2: Создание фильтра с помощью StaticFilter

Альтернативный способ ручного инстанцирования фильтра - с использованием класса StaticFilter. Класс StaticFilter - что-то вроде "заместителя" ("proxy"), который предназначен для автоматического инстанцирования фильтра, настройки и выполнения. Рассмотрим, например, как создать тот же фильтр StringTrim, настроить его и вызывать его метод filter():

<?php
// Создание и выполнение фильтра StringTrim через "заместителя" StaticFilter.
$filteredValue = \Zend\Filter\StaticFilter::execute(' name@example.com  ', 
                        'StringTrim', ['charlist' => "\r\n\t "]);
						
// Ожидаемый вывод фильтра - строка 'name@example.com'.

Класс StaticFilter предоставляет метод execute(), который принимает три аргумента: входное значение, имя фильтра, который нужно применить, и массив опций для выбранного фильтра.

В строке 3 мы вызываем метод execute(), чтобы автоматически создать фильтр StringTrim, вызвать его метод setCharList() и передать входное значение методу filter(). Это крайне полезно, так как может быть выполнено в одну строчку кода.

8.3.3. Способ 3: Создание фильтра из массива

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

В качестве примера покажем, как создать все тот же фильтр StringTrim с помощью фабрики:

<?php
// Предполагается, что вы вызываете следующий код внутри метода
// addInputFilter() модели формы.

$inputFilter->add([
  // ...  
  'filters'  => [
    [
      'name' => 'StringTrim',
      'options' => [
        'charlist' => "\r\n\t "
      ]	  
    ],
  ],                
  // ...
];

В фрагменте кода выше мы вызываем метод add(), предоставляемый классом-контейнером InputFilter (строка 5). Метод add() принимает массив, который имеет ключ filters. Как правило, фильтры регистрируются под этим ключом (строка 7). Фильтры, зарегистрированные под этим ключом, вставляются в цепь фильтров в том же порядке, что и в списке.

Конфигурация фильтра обычно состоит из имени - name (строка 9) и опций - options (строка 10). Имя - это полностью определенное имя класса фильтра (например, Zend\Filter\StringTrim), либо его псевдоним (StringTrim). options - это массив, состоящий из опций конкретного фильтра. Когда класс фабрики инстанцирует фильтр, он передает список опций методу конструктора фильтра, а конструктор при необходимости инициализирует фильтр.