Что такое валидатор и зачем он нужен?

Разработчики модулей создавая модули часто сталкиваются с задачей валидации форм, которые отправляет пользователь. Например, практически в любой форме есть поля, обязательные для заполнения. Так же есть поля, значения которых нужно проверить на наличие в базе данных, в некоторых полях может находиться файл, размер которого нам нужно проверить, ссылка, правильность которой тоже нужно проверить или же email адрес в котором, например, нужно проверить не только корректность текста до и после символа @, но и наличие MX записей для указанного домена.

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

Что позволяет делать валидатор?

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

В JohnCMS используется laminas-validator, большинство существующих правил, которые описаны в официальной документации будут работать и в JohnCMS, но есть правила для которых требуются дополнительные зависимости и эти правила могут не работать, но таких как правило единицы и они редко используются.

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

<?php

require 'system/bootstrap.php';

// Массив полей и значений
$data = [
    'test'   => '',
    'number' => 100,
    'email'  => 'email@example.ru',
    'model'  => 110,
];

// Настройки валидатора
$rules = [
    // Название поля => [ правила валидации и их параметры ]
    'test'   => [
        'NotEmpty',
        'StringLength' => [
            'min' => 6,
            'max' => 80,
        ],
    ],
    'number' => [
        'NotEmpty',
        'LessThan' => ['max' => 90],
    ],
    'email'  => [
        'EmailAddress' => [
            'useMxCheck' => true,
        ],
    ],
    'model'  => [
        'ModelExists' => [
            'model' => \Johncms\Users\User::class,
            'field' => 'id',
        ],
    ],
];

// Валидация
$validator = new \Johncms\Validator\Validator($data, $rules);
if ($validator->isValid()) {
    echo 'OK';
} else {
    d($validator->getErrors());
}

Здесь массив $data содержит набор данных, которые будут проверяться. Часто это данные из формы, полученные методом POST или GET.

Массив $rules содержит набор правил и их настройку. В качестве ключа указывается название поля из массива $data, а в качестве массива со значениями используется валидатор или набор валидаторов и их настройки. Например в первом правиле проверяется значение поля под названием test, к нему применяется валидатор NotEmpty и StringLength. Валидатор NotEmpty проверяет не пустое ли значение в поле test, а валидатор StringLength проверяет длину значения. В данном случае длина значения должна быть от 6 до 80 символов.

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

Многие популярные валидаторы мы рассмотрим отдельно. Пока можете попробовать выполнить код выше. Для этого в корне вашего сайта создайте файл test.php и вставьте в него этот код. После этого откройте в браузере страницу site.ru/test.php. Вы увидите следующий результат:

Array
(
    [test] => Array
        (
            [isEmpty] => Поле является обязательным и не может быть пустым
        )

    [number] => Array
        (
            [notLessThan] => The input is not less than '90'
        )

    [email] => Array
        (
            [emailAddressInvalidMxRecord] => 'example.ru' Похоже, что записи MX или A для адреса электронной почты не действительны
        )

    [model] => Array
        (
            [modelNotFound] => Нет записей, соответствующих введенным данным
        )

)

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

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

Поддерживаемые параметры

• inclusive: Включая максимальное значение. Если задано true, то значение равное максимальное значение будет проходить валидацию. Если задано false, то значение равное максимальному значению не будет проходить валидацию.

• max: Устанавливает максимальное значение.

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

// Массив полей и значений
$data = [
    'test' => 60,
];

// Настройки валидатора
$rules = [
    'test' => [
        'LessThan' => [
            'max'       => 60,
            'inclusive' => true,
        ],
    ],
];

// Валидация
$validator = new \Johncms\Validator\Validator($data, $rules);
if ($validator->isValid()) {
    echo 'OK';
} else {
    d($validator->getErrors());
}

Этот пример выведет "OK", т.к. включен параметр inclusive и значение равно максимальному.

// Массив полей и значений
$data = [
    'test' => 60,
];

// Настройки валидатора
$rules = [
    'test' => [
        'LessThan' => [
            'max'       => 60,
            'inclusive' => false,
        ],
    ],
];

// Валидация
$validator = new \Johncms\Validator\Validator($data, $rules);
if ($validator->isValid()) {
    echo 'OK';
} else {
    d($validator->getErrors());
}

А этот пример выведет ошибку т.к. параметр inclusive имеет значение false т.к. этот параметр исключает максимальное значение.

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

По умолчанию этот валидатор проверяет, находится ли значение между min и max, используя минимальное значение по умолчанию, равное 0, и максимальное значение по умолчанию, равное NULL (то есть неограниченное). Таким образом, без каких-либо опций, валидатор только проверяет, что ввод является строкой.

Поддерживаемые параметры

• encoding: Устанавливает кодировку ICONV в которой будет проверяться строка.

• min: Устанавливает минимально допустимую длину строки.

• max: Устанавливает максимально допустимую длину для строки.

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

// Массив полей и значений
$data = [
    'test' => 'Строка',
];

// Настройки валидатора
$rules = [
    'test' => [
        'StringLength' => [
            'min'      => 3,
            'max'      => 60,
            'encoding' => 'UTF-8',
        ],
    ],
];

// Валидация
$validator = new \Johncms\Validator\Validator($data, $rules);
if ($validator->isValid()) {
    echo 'OK';
} else {
    d($validator->getErrors());
}

В указанном примере валидатор проверит строку в кодировке UTF-8 на длину от 3 до 60 символов.

Проверка только минимальной длины:

// Массив полей и значений
$data = [
    'test' => 'Строка',
];

// Настройки валидатора
$rules = [
    'test' => [
        'StringLength' => [
            'min' => 3
        ],
    ],
];

// Валидация
$validator = new \Johncms\Validator\Validator($data, $rules);
if ($validator->isValid()) {
    echo 'OK';
} else {
    d($validator->getErrors());
}

В этом примере будет проверяться только минимальная длина строки (3 символа). Максимальная будет считаться не ограниченной.

Проверка только максимальной длины:

// Массив полей и значений
$data = [
    'test' => 'Строка',
];

// Настройки валидатора
$rules = [
    'test' => [
        'StringLength' => [
            'max' => 50
        ],
    ],
];

// Валидация
$validator = new \Johncms\Validator\Validator($data, $rules);
if ($validator->isValid()) {
    echo 'OK';
} else {
    d($validator->getErrors());
}

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

Строгое ограничение длины строки:

// Массив полей и значений
$data = [
    'test' => 'Строка',
];

// Настройки валидатора
$rules = [
    'test' => [
        'StringLength' => [
            'max' => 6,
            'min' => 6,
        ],
    ],
];

// Валидация
$validator = new \Johncms\Validator\Validator($data, $rules);
if ($validator->isValid()) {
    echo 'OK';
} else {
    d($validator->getErrors());
}

А в этом примере мы строго ограничили длину строки 6 символами. Т.е. проверка пройдет только если строка будет длиной в 6 символов. Больше или меньше не допускается.

Валидатор ModelExists позволяет проверить существование записи в базе данных. Это хорошо подходит для тех случаев, когда у вас в форме есть привязка к каким-то существующим записям в базе данных.

Для работы этого валидатора вам потребуется существующая модель.

Поддерживаемые параметры

• model: Класс модели, который будет использоваться для построения запроса к БД.

• field: Столбец в БД по которому будет осуществляться поиск записи.

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

// Массив полей и значений
$data = [
    'test' => 45,
];

// Настройки валидатора
$rules = [
    'test' => [
        'ModelExists'   => [
            'model' => \Johncms\Users\User::class,
            'field' => 'id',
        ],
    ],
];

// Валидация
$validator = new \Johncms\Validator\Validator($data, $rules);
if ($validator->isValid()) {
    echo 'OK';
} else {
    d($validator->getErrors());
}

В указанном примере будет выполнена проверка наличия пользователя c идентификатором 45 в таблице users.

Запрос который будет выполнен:

SELECT * FROM `users` WHERE `id` = 45

В результате, если будет найдена запись с id = 45, то валидатор будет считать проверку успешной, если не найдет, то вернёт ошибку.

Рассмотрим ещё один пример:

// Массив полей и значений
$data = [
    'test' => 'admin',
];

// Настройки валидатора
$rules = [
    'test' => [
        'ModelExists'   => [
            'model' => \Johncms\Users\User::class,
            'field' => 'name',
        ],
    ],
];

// Валидация
$validator = new \Johncms\Validator\Validator($data, $rules);
if ($validator->isValid()) {
    echo 'OK';
} else {
    d($validator->getErrors());
}

В этом примере будет выполнен поиск записи у которой поле name = admin.

Будет выполнен следующий запрос:

SELECT * FROM `users` WHERE `name` = 'admin'

Результат будет такой же как и в случае с id. Если будет найдена строка с полем name = admin, то валидация пройдет успешно, если нет, будет возвращена ошибка.

Валидатор EmailAddress позволяет выполнить различные проверки email адреса. Валидатор сначала разбивает адрес электронной почты на local-part@hostname и пытается сопоставить их с известными спецификациями для адресов электронной почты и имен хостов.

Поддерживаемые параметры

• allow: Определяет, какой тип доменных имен принимает валидатор. Эта опция используется вместе с опцией hostnameValidator для установки валидатора имени хоста. Возможные значения этой опции определены в константах ALLOW_ * валидатора Hostname:

  • ALLOW_DNS: (по умолчанию) Разрешает доменные имена (например example.com)

  • ALLOW_IP: Разрешает IP адреса.

  • ALLOW_LOCAL: Разрешает локальные домены такие как localhost или www.localdomain

  • ALLOW_URI: Разрешает имена хостов в универсальном синтаксисе URI. См. RFC 3986

  • ALLOW_ALL: Разрешить все типы хостов.

• useDeepMxCheck: Указывает валидатору на необходимость усиленной проверки MX записей домена. Если для этого параметра установлено значение true, то в дополнение к записям MX также используются записи A, A6 и AAAA для проверки того, принимает ли сервер электронную почту. Эта опция по умолчанию имеет значение false.

• useDomainCheck: Определяет, должна ли быть проверена часть домена. Если для этого параметра установлено значение false, будет проверяться только локальная часть адреса электронной почты. В этом случае валидатор имени хоста не будет вызван. Эта опция по умолчанию имеет значение true.

• hostnameValidator: Задает экземпляр объекта валидатора имени хоста, с помощью которого будет проверяться доменная часть адреса электронной почты.

• useMxCheck: Определяет, должны ли быть обнаружены записи MX с сервера. Если для этого параметра задано значение true, то MX-записи используются для проверки того, принимает ли сервер электронную почту или нет. Эта опция по умолчанию имеет значение false.

Пример использования

Рассмотрим наиболее распространенный пример, которого скорее всего вам будет достаточно. Этот пример проверяет существование домена и возможность принимать email. Т.е. выполняется максимально возможная проверка. Она пропустит только точно существующий домен с MX записями.

// Массив полей и значений
$data = [
    'test' => 'info@johncms.com',
];

// Настройки валидатора
$rules = [
    'test' => [
        'EmailAddress'   => [
            'allow'          => Laminas\Validator\Hostname::ALLOW_DNS,
            'useMxCheck'     => true,
            'useDeepMxCheck' => true,
        ],
    ],
];

// Валидация
$validator = new \Johncms\Validator\Validator($data, $rules);
if ($validator->isValid()) {
    echo 'OK';
} else {
    d($validator->getErrors());
}

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

По умолчанию этот валидатор работает иначе, чем вы ожидаете, работая с PHP функцией empty(). В частности, этот валидатор будет оценивать как целое число 0, так и строку «0» как пустые.

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

Поддерживаемые параметры

• type: Устанавливает тип проверки, которая будет выполнена.

Обрабатываемые типы

• boolean: Возвращает false, когда логическое значение равно false.

• integer: Возвращает false, когда задано целое число 0. По умолчанию эта проверка не активирована и возвращает true для любых целочисленных значений.

• float: Возвращает false, когда задано значение с плавающей запятой 0.0. По умолчанию эта проверка не активирована и возвращает true для любых значений с плавающей запятой.

• string: Возвращает false, когда задана пустая строка.

• zero: Возвращает false, когда задан один символ ноль ('0').

• empty_array: Возвращает false, когда задан пустой массив.

• null: Возвращает false, когда задано значение null.

• php: Возвращает false везде, где PHP empty () возвращает true.

• space: Возвращает false, если задана строка, содержащая только пробел.

• object: Возвращает true. false будет возвращено, когда объект не разрешен, но объект задан.

• object_string: Возвращает false, когда объект задан, а его метод __toString () возвращает пустую строку.

• object_count: Возвращает false, когда объект задан, он реализует Countable, и его количество равно 0.

• all: Возвращает false для всех вышеперечисленных типов.

Рассмотрим пример как передавать эти параметры в валидатор.

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

// Массив полей и значений
$data = [
    'test' => 0,
];

// Настройки валидатора
$rules = [
    'test' => [
        'NotEmpty' => [
            'type' => [
                'integer',
                'zero',
            ],
        ],
    ],
];

// Валидация
$validator = new \Johncms\Validator\Validator($data, $rules);
if ($validator->isValid()) {
    echo 'OK';
} else {
    d($validator->getErrors());
}

Как видите, для валидатора NotEmpty задан массив настроек, в нем передается параметр type со значениями из списка выше (обрабатываемые типы).

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

Для работы этого валидатора вам потребуется существующая модель.

Поддерживаемые параметры

• model: Класс модели, который будет использоваться для построения запроса к БД.

• field: Столбец в БД по которому будет осуществляться поиск записи.

• exclude: Параметры для задания условий исключения из выборки. Может содержать анонимную функцию или массив с полями field и value.

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

// Массив полей и значений
$data = [
    'test' => 'admin@admin.ru',
];

// Настройки валидатора
$rules = [
    'test' => [
        'ModelNotExists' => [
            'model'   => \Johncms\Users\User::class,
            'field'   => 'mail',
            'exclude' => static function ($query) {
                return $query->where('name', '!=', 'admin')->where('id', '!=', 1);
            },
        ],
    ],
];

// Валидация
$validator = new \Johncms\Validator\Validator($data, $rules);
if ($validator->isValid()) {
    echo 'OK';
} else {
    d($validator->getErrors());
}

В примере выше выполняется проверка наличия в таблице users пользователя с полем mail, содержащим admin@admin.ru. При этом из выборки исключаются строки с name = admin и id = 1. Для расширения запроса на выборку используется анонимная функция. Она позволяет дополнять запрос любыми условиями. Валидатор выполнит следующий запрос:

select * from `users` where (`name` != 'admin' and `id` != 1) and `mail` = 'admin@admin.ru' limit 1

Рассмотрим более простой пример, где в параметр exclude передается массив:

// Массив полей и значений
$data = [
    'test' => 'admin@admin.ru',
];

// Настройки валидатора
$rules = [
    'test' => [
        'ModelNotExists' => [
            'model'   => \Johncms\Users\User::class,
            'field'   => 'mail',
            'exclude' => [
                'field' => 'name',
                'value' => 'admin',
            ],
        ],
    ],
];

// Валидация
$validator = new \Johncms\Validator\Validator($data, $rules);
if ($validator->isValid()) {
    echo 'OK';
} else {
    d($validator->getErrors());
}

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

select * from `users` where `name` != 'admin' and `mail` = 'admin@admin.ru' limit 1

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

// Массив полей и значений
$data = [
    'test' => 'admin@admin.ru',
];

// Настройки валидатора
$rules = [
    'test' => [
        'ModelNotExists' => [
            'model'   => \Johncms\Users\User::class,
            'field'   => 'mail',
        ],
    ],
];

// Валидация
$validator = new \Johncms\Validator\Validator($data, $rules);
if ($validator->isValid()) {
    echo 'OK';
} else {
    d($validator->getErrors());
}

При таких настройках валидатор просто проверит наличие записи с mail = admin@admin.ru. Если запись будет найдена, то валидатор вернёт ошибку. Если нет, проверка пройдет успешно.

Запрос, который выполнит валидатор при этих настройках будет таким:

select * from `users` where `mail` = 'admin@admin.ru' limit 1

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

Пример использования

В указанном примере валидатор Flood добавлен для того же поля, что и валидатор токена.

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

Поддерживаемые параметры

• bans: Массив банов, наличие которых будет проверяться. Параметр не обязателен. По умолчанию проверяется бан "Полная блокировка".

Пример использования

В указанном примере будет проверяться бан для форума (11) и гостевой (13). Если у пользователя есть хотя бы 1 из этих банов, проверка не пройдет.

Валидатор Csrf предназначен для проверки токена csrf. Токен предназначен для защиты формы от подделки запроса. Данный валидатор работает в паре с генератором токенов \Johncms\Security\Csrf

Поддерживаемые параметры

• tokenId: Идентификатор токена. Если не задан, используется токен по умолчанию для всего сайта.

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

В указанном примере будет проверяться токен по умолчанию.

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

Более подробно работу с токенами мы рассмотрим в отдельной статье.

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

Поддерживаемые параметры

• sessionField: Указывается ключ в сессии из которого валидатор будет использовать код. По умолчанию: code

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

В указанном выше примере код код будет использоваться из переменной по умолчанию $_SESSION['code']

А в этом примере будет использован код из переменной $_SESSION['captcha_code']

Более подробно работу с формами и с капчей рассмотрим в отдельной статье.