9.6. Примеры использования валидаторов

Далее мы рассмотрим примеры использования самых важных стандартных валидаторов. Мы опишем методы (и опции) валидатора и приведем фрагменты кода, показывающие, как инстанцировать валидатор и применить его к входным данным.

9.6.1. Валидаторы для проверки соответствия значения определенному формату

В этом разделе мы рассмотрим примеры использования валидаторов, связанных с проверкой соответствия входного значения определенному формату

9.6.1.1. Ip Validator

Класс валидатора предназначен для проверки того, является ли входное значение действительным IP-адресом. Если входное значение является IPv4-адресом ³², IPv6-адресом ³³, IPvFuture-адресом ³⁴ или буквенным IPv6-адресом [буквенный_^ipv6_адрес], валидатор возвращает значение true; иначе возвращается false. В случае неудачи, сообщения об ошибках можно извлечь с помощью метода getMessages().

³²⁾ Четвертая версия интернет протокола (Internet Protocol version 4 - IPv4) использует адреса, как правило, состоящие из четырех октетов, разделенных точками. В виде десятичных чисел запись выглядит как "192.168.56.101".

³³⁾ Шестая версия интернет протокола (Internet Protocol version 6 - IPv6) использует адреса, как правило, состоящие из восьми групп четырех шестнадцатеричных цифр, разделенных двоеточиями, например, "2001:0db8:85a3:0000:0000:8a2e:0370:7334".

³⁴⁾ IPvFuture весьма расплывчато определен в главе 3.2.2 RFC 3986.

³⁵⁾ Буквенный IPv6-address - это модификация обычного IPv6-адреса для использования внутри URL. (проблема с оригинальными IPv6-адресами в том, что символы ":" и "." в URL являются разделителями.)

Public-методы, предоставляемые валидатором Ip перечислены в таблице 9.3:

Метод setOptions() предоставляет возможность определить разрешенные типа IP-адресов:

• allowipv4 для разрешения IPv4-адресов;
• allowipv6 для разрешения IPv6-адресов;
• allowipvfuture для разрешения IPvFuture-адресов;
• allowliteral для разрешения буквенных IPv6-адресов.

По умолчанию разрешены все вышеперечисленные адреса кроме буквенных IPv6.

Ниже показан пример кода, демонстрирующий использование валидатора Ip.

<?php
use Zend\Validator\Ip;

// Создаем валидатор Ip.
$validator = new Ip();

// Настраиваем валидатор.
$validator->setOptions([
    'allowipv4'      => true,  // Разрешаем IPv4-адреса.
    'allowipv6'      => true,  // Разрешаем IPv6-адреса.
    'allowipvfuture' => false, // Разрешаем IPvFuture-адреса.
    'allowliteral'   => true,  // Разрешаем IP-адреса в буквенном формате.
  ]);

// Проверяем, является ли входное значение действительным IP-адресом (IPv4).
$isValid = $validator->isValid('192.168.56.101'); // Возвращает true

// Проверяем, является ли входное значение действительным IP-адресом (IPv6).
$isValid2 = $validator->isValid(
       '2001:0db8:85a3:0000:0000:8a2e:0370:7334'); // Возвращает true

// Передает недействительную строку (не содержащую IP-адрес).       
$isValid3 = $validator->isValid('abc'); // Возвращает false

9.6.1.2. Hostname Validator

Валидатор Hostname предназначен для проверки того, является ли заданное значение именем хоста, принадлежащим к набору разрешенных типов. Такими типами являются:

• DNS-имя (например, "example.com");
• IP-адрес (например, "192.168.56.101");
• имя локального хоста (например, "localhost").

Public-методы, предоставляемые этим валидатором, перечислены в таблице 9.4:

Вы можете определить, какие типы имен хостов разрешены, с помощью метода setAllow(). Он принимает комбинацию следующих констант:

• ALLOW_DNS Разрешает доменные имена (например, example.com);
• ALLOW_IP Разрешает IP-адреса;
• ALLOW_LOCAL Разрешает имена локальных сетей (например, localhost, www.localdomain);
• ALLOW_URI Разрешает имена хостов URI.
• ALLOW_ALL Разрешает все типы имен хостов.

По умолчанию разрешены только доменные имена.

Проверка имени хоста состоит из нескольких этапов, некоторые из которых могут быть пропущены в зависимости от опций валидатора:

1. Если входное значение выглядит как IP-адрес, оно проверяется внутренним валидатором IP-адреса. Используемый для этого валидатор IP-адреса можно переопределить методом setIpValidator()`.

2. Имя хоста делится на части домена (разделенные точками ".").

3. Домен верхнего уровня (TLD) сверяется с белым списком доступных TLD. (это действие можно отключить методом useTldCheck()).

4. Каждая часть домена проверяется в соответствии с правилами для допустимых доменных имен. Если доменное имя - IDN ³⁶, оно сверяется с правилами действительных IDN (проверку IDN можно отключить методом useIdnCheck().

³⁶⁾ Интернационализованное доменное имя (internationalized domain name - IDN) - это доменное имя, которое содержит хотя бы одну метку, полностью или частично составленную из букв национальных алфавитов, например, арабского, китайского или русского.

Ниже показан пример кода, демонстрирующий использование валидатора Hostname.

<?php
use Zend\Validator\Hostname;

// Создаем валидатор Hostname.
$validator = new Hostname();

// Настраиваем валидатор.
$validator->setAllow(Hostname::ALLOW_DNS|Hostname::ALLOW_IP);

// Проверяем имя хоста.
$isValid = $validator->isValid('site1.example.com'); 
// Возвращает true.
$isValid2 = $validator->isValid('abc'); 
// Возвращает false (недействительное имя хоста).

9.6.1.3. Валидатор Uri

Валидатор Uri предназначен для проверки того, является ли входное значение единообразным идентификатором ресурса (Uniform Resource Identifier - URI) ³⁷. При неудачной валидации сообщения об ошибках могут быть извлечены с помощью метода валидатора getMessages().

Пусть вас не смущает термин URI. В большинстве случаев вы можете считать URI обычными URL.

³⁷⁾ Единообразный идентификатор ресурса (URI) - это компактная последовательность символов, идентифицирующая абстрактный или физический ресурс. Единый указатель ресурса (URL) является типом URI. Однако, это не значит, что все URI это URL.

Public-методы, предоставляемые валидатором Uri, перечислены в таблице 9.5:

Валидатор Uri внутренне использует так называемый объект обработчика URI, ответственный за разбор строки URI. По умолчанию в качестве обработчика URI используется класс Zend\Uri\Uri (если хотите, можете установить свой собственный обработчик URI с помощью метода setUriHandler()).

URI может быть абсолютным (например,"http://example.com/blog/2014/02/02/edit") или относительным (например, "2014/02/02/edit"). Вы можете указать, должен ли валидатор считать абсолютные и/или относительные URI допустимыми. Для этого используйте соответственно методы setAllowAbsolute() и setAllowRelative(). По умолчанию, оба типа URI считаются допустимыми.

Ниже показан пример кода, демонстрирующий использование валидатора Uri.

<?php
use Zend\Validator\Uri;

// Создаем валидатор Uri.
$validator = new Uri();

// Настраиваем валидатор.
$validator->setAllowAbsolute(true);
$validator->setAllowRelative(true);

// Проверяем URI.
$isValid = $validator->isValid('http://site1.example.com/application/index/index'); 
// Возвращает true.
$isValid2 = $validator->isValid('index/index'); 
// Возвращает true.

9.6.1.4. Валидатор Date

Валидатор Date предназначен для проверки того, являются ли входные данные датой в заданном формате.

При неудачной валидации сообщения об ошибках могут быть извлечены с помощью метода валидатора getMessages().

Public-методы, предоставляемые валидатором Date, перечислены в таблице 9.6:

Для установки ожидаемого формата даты используйте метод setFormat().

Фильтр DateTimeFormatter внутренне использует класс DateTime из стандартной библиотеки PHP для преобразования и форматирования дат. Доступные форматы данных вы можете посмотреть в документации PHP для класса DateTime.

Ниже показан пример кода, демонстрирующий использование валидатора Date.

<?php
use Zend\Validator\Date;

// Создаем экземпляр валидатора.
$validator = new Date();

// Настраиваем валидатор.
$validator->setFormat('Y-m-d');

// Проверяем, является ли входное значение датой в ожидаемом формате.
$isValid = $validator->isValid('2014-04-04'); // Возвращает true.
$isValid2 = $validator->isValid('April 04, 2014'); // Возвращает false (непредвиденный формат).

9.6.1.5. Валидатор Regex

Этот валидатор позволяет проверить, соответствует ли заданная строка какому-либо регулярному выражению. Он возвращает true, если строка совпадает с регулярным выражением, иначе возвращается false. При неудачной валидации сообщения об ошибках могут быть извлечены с помощью метода валидатора getMessages().

Public-методы, предоставляемые валидатором Regex, перечислены в таблице 9.7:

Метод setPattern() позволяет задать регулярное выражение для проверки соответствия.

Синтаксис и примеры регулярных выражений можно посмотреть в разделе Шаблоны PCRE документации PHP.

Ниже показан пример кода, демонстрирующий использование валидатора Regex. Здесь мы используем регулярное выражение для проверки того, является ли входная строка действительным IPv4-адресом (такой адрес, как правило, состоит из четырех групп цифр, разделенных точками).

<?php
use Zend\Validator\Regex;

// Создаем валидатор Regex.
$validator = new Regex();

// Задаем регулярного выражения для проверки IP-адреса.
$validator->setPattern('\b\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}\b');

// Проверка на соответствие регулярному выражению.
$isValid = $validator->isValid("127.0.0.1"); // возвращает true.
$isValid2 = $validator->isValid("123"); // возвращает false.

9.6.2. Валидаторы для проверки того, что числовое значение лежит в заданном диапазоне

В этом разделе мы рассмотрим примеры использования валидаторов, связанных с проверкой того, находится ли числовое значение в определенном диапазоне.

9.6.2.1. Валидатор NotEmpty

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

Public-методы, предоставляемые валидатором NotEmpty, перечислены в таблице 9.8:

Метод setType() указывает, какие типы переменных считать пустыми значениями. Этот метод принимает один аргумент $type, который может быть либо комбинацией ИЛИ констант, перечисленных в таблице 9.9, либо массивом, содержащим буквенные эквиваленты этих констант.

Ниже показан пример кода, демонстрирующий использование валидатора NotEmpty.

<?php
use Zend\Validator\NotEmpty;

// Создаем экземпляр валидатора.
$validator = new NotEmpty();

// Настраиваем валидатор.
$validator->setType(NotEmpty::ALL);

// Проверяем, не является ли входное значение пустым.
$isValid1 = $validator->isValid('some string'); // возвращает true
$isValid2 = $validator->isValid(''); // возвращает false 
$isValid3 = $validator->isValid(0); // возвращает false

9.6.2.2. Валидатор Between

Валидатор Between проверяет, находится ли число в определенном диапазоне (min, max), либо включительно (по умолчанию), либо исключительно.

Public-методы, предоставляемые валидатором Between, перечислены в таблице 9.10:

Диапазон может быть задан с помощью методов setMin() и setMax().

По умолчанию, валидатор осуществляет сравнения включительно (чтобы проверить, принадлежит ли значение заданному диапазону, он сравнивает, значение больше или равно нижней границы или нет; и меньше или равно верхней границы или нет). Эту опцию можно изменить с помощью метода setInclusive(). Он сообщает валидатору, какое выполнять сравнение: включительно (для этого нужно передать аргумент true) или исключительно (аргумент false).

Ниже показан пример кода, демонстрирующий использование валидатора Between.

<?php
use Zend\Validator\Between;

// Создаем экземпляр валидатора.
$validator = new Between();

// Настраиваем валидатор.
$validator->setMin(1);
$validator->setMax(10);
$validator->setInclusive(true);

$isValid1 = $validator->isValid(5); // возвращает true.
$isValid2 = $validator->isValid(10); // возвращает true.
$isValid3 = $validator->isValid(0); // возвращает false (значение слишком мало).
$isValid4 = $validator->isValid(15); // возвращает false (значение слишком велико).

9.6.2.3. Валидатор InArray

Валидатор InArray проверяет, принадлежит ли входное значение заданному массиву значений. Public-методы, предоставляемые валидатором InArray, перечислены в таблице 9.11:

Метод setHaystack() позволяет задать массив допустимых значений. Метод isValid() будет искать в этом массиве входную переменную $value`.

Если массив содержит вложенные значения, и вы хотите провести среди них рекурсивный поиск, используйте метод setRecursive(). Этот метод принимает один единственный булевый флаг. Если флаг установлен в true, поиск будет осуществляться рекурсивно; иначе вложенные уровни будут проигнорированы.

Метод setStrict() предоставляет возможность указать валидатору, каким образом будут сравниваться входное значение и значения в массиве. Он принимает комбинацию следующих констант:

• COMPARE_NOT_STRICT Не осуществлять строгую проверку типа переменной.
• COMPARE_NOT_STRICT_AND_PREVENT_STR_TO_INT_VULNERABILITY Не осуществлять строгую проверку типа переменной, но не допускать ложноположительных сравнений строки с integer-значением (например, "asdf" == 0). Это опция по умолчанию.
• COMPARE_STRICT Проверять и тип переменной, и значение.

Ниже показан пример кода, демонстрирующий использование валидатора InArray.

<?php
use Zend\Validator\InArray;

// Создаем экземпляр валидатора.
$validator = new InArray();

// Настраиваем валидатор.
$validator->setHaystack([1, 3, 5]);

// Perform validation.
$isValid1 = $validator->isValid(1); // возвращает true.
$isValid2 = $validator->isValid(2); // возвращает false.

9.6.2.4. Валидатор StringLength

Валидатор StringLength, принадлежит ли длина входной строки заданному диапазону (включительно). Он возвращает true тогда и только тогда, когда длина строки значения как минимум равна опции min и не больше опции max (если опция max не нулевая).

Public-методы, предоставляемые валидатором StringLength, перечислены в таблице 9.12:

По умолчанию, валидатор StringLength считает действительной любую длину строки. Используйте методы setMin() и/или setMax(), чтобы задать нижнюю и верхнюю границу для допустимой длины. Существует три возможных способа это сделать:

• Используя только метод setMin(), чтобы разрешить строки с заданной нижней границей и без верхней границы;
• Используя только метод setMax(), чтобы разрешить строки с нижней границей равной 0 и заданной верхней границей;
• Используя оба метода, чтобы разрешить строки с длиной, лежащей в заданном диапазоне.

По умолчанию, PHP-движок использует для строк кодировку UTF-8. Если входная строка использует другую кодировку, эту кодировку следует указать с помощью метода валидатора setEncoding().

Ниже показан пример кода, демонстрирующий использование валидатора StringLength.

<?php
use Zend\Validator\StringLength;

// Создаем экземпляр валидатора.
$validator = new StringLength();

// Настраиваем валидатор.
$validator->setMin(1);
$validator->setMax(10);

$isValid1 = $validator->isValid("string"); // возвращает true.
$isValid2 = $validator->isValid(""); // возвращает false (слишком короткое значение).
$isValid3 = $validator->isValid("a very long string"); // возвращает false (слишком длинное значение).

9.6.3. Организация валидаторов в цепь

Валидаторы могут быть организованы в последовательность. Это делается с помощью класса ValidatorChain. При запуске подобного составного валидатора, входное значение по очереди передается всем валидатором. Метод isValid() валидатора ValidatorChain возвращает true, если все валидаторы в цепочке возвращают true; иначе он возвращает false.

Класс ValidatorChain внутренне используется классом-контейнером InputFilter для хранения последовательности валидаторов, присоединенных к полю модели формы.

Public-методы, предоставляемые валидатором ValidatorChain, перечислены в таблице 9.12:

Пример цепочки валидаторов показан на рисунке 9.2. Эта цепь состоит из валидатора NotEmpty, за которым следует валидатор StringLength, за которым в свою очередь следует валидатор Date. При выполнении этой цепи первым делом запускается валидатор NotEmpty, проверяющий, что значение не является пустым, затем StringLength, проверяющий, что длина входной строки принадлежит диапазону (1,16) включительно, и наконец валидатор Date`, проверяющий, что входное значение является датой в формате "ГГГГ-ММ-ДД".

Рисунок 9.2. Цепь валидаторов

Для создания цепочки валидаторов, как на рисунке 9.2, используем следующий код:

<?php
// Инстанцируем цепь валидаторов.
$validator = new \Zend\Validator\ValidatorChain();

// Добавляем валидаторы в цепочку.
$validator->attachByName('NotEmpty');
$validator->attachByName('StringLength', ['min'=>1, 'max'=>16]);
$validator->attachByName('Date', ['format'=>'Y-m-d']);

// Выполняем все валидаторы в цепи.
$isValid = $validator->isValid('2014-04-04'); // Возвращает true.

9.6.4. Пользовательская валидация с помощью валидатора Callback

Валидатор Callback может быть оберткой для вашего собственного алгоритма валидации. Это может быть полезно, например, когда стандартные валидаторы не подходят, и вам нужно применить к данным свой алгоритм проверки. Public-методы, предоставляемые валидатором Callback перечислены в таблице 9.14.

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

9.6.4.1. Пример

Чтобы продемонстрировать использование метода Callback, добавим валидатор телефонного номера к нашему классу модели формы ContactForm. Этот валидатор будет проверять номер телефона, вводимый посетителем сайта.

Валидатор должен делать проверку на два общепринятых формата телефонных номеров:

• международный формат вида "1 (234) 567-8901";
• и локальный формат вида "567-8901".

Так как ZF3 не предоставляет стандартного валидатора для осуществления подобной операции фильтрации номера, мы будем использовать валидатор-обертку Callback. Для этого внесем следующие изменения в код нашего класса ContactForm:

<?php
// ...
class ContactForm extends Form
{    
  // ..
  protected function addElements() {
    // ...
	
    // Добавляем поле "phone"
    $this->add([
        'type'  => 'text',
        'name' => 'phone',
        'attributes' => [                
          'id' => 'phone'
        ],
        'options' => [
          'label' => 'Your Phone',
        ],
      ]);
  }
    
  private function addInputFilter() 
  {
    // ...
        
    $inputFilter->add([
            'name'     => 'phone',
            'required' => true,                
            'validators' => [
                [
                  'name' => 'Callback',
                  'options' => [
                     'callback' => [$this, 'validatePhone'],
                     'callbackOptions' => [
                     'format' => 'intl'
                  ]
                ]                        
              ]                    
            ]
        );
  }
        
  // Пользовательский валидатор для телефонного номера.
  public function validatePhone($value, $context, $format) 
  {
    // Определяем корректную длину и шаблон телефонного номера 
    // в зависимости от формата.
    if($format == 'intl') {
      $correctLength = 16;
      $pattern = '/^\d\ (\d{3}\) \d{3}-\d{4}$/';
    } else { // 'local'
      $correctLength = 8;
      $pattern = '/^\d{3}-\d{4}$/';
    }
                
    // Проверяем длину номера.
    if(strlen($value)!=$correctLength)
      return false;

    // Проверяем, соответствует ли значение шаблону.
    $matchCount = preg_match($pattern, $value);
        
    return ($matchCount!=0)?true:false;
  }
}

Во фрагменте выше мы создаем поле phone в нашей форме обратной связи ContactForm (пропустите, если у вас уже есть такое поле).

В строках 26-40 мы добавляем в цепь валидаторов фильтра входных данных валидатор Callback для поля "phone".

В строках 44-64 находится метод обратного вызова validatePhone(). Этот метод принимает три аргумента: параметр $value - телефонный номер, который нужно валидировать, параметр $context, принимающий значения каждого поля формы (некоторым валидаторам нужно также обращаться к значениям других полей формы); и параметр $format - ожидаемый формат телефонного номера ("intl" или "local").

Внутри метода обратного вызова мы делаем следующее:

1. Вычисляем корректную длину телефонного номера, проверяем, корректна ли длина для выбранного формата номера.
2. Сопоставляем номер телефона с шаблоном регулярного выражения для выбранного формата номера.