Правила валидации

Все правила живут в пространстве имён Johncms\Validator\Rules. Параметры передаются именованными аргументами конструктора, поэтому указывать нужно только то, что отличается от значений по умолчанию.

Общие для большинства правил параметры:

• allowEmpty — разрешить пустое значение. По умолчанию false: поле, у которого есть правила, обязательно. Подробнее — в обзоре.

• message — свой текст ошибки вместо стандартного.

NotEmpty — значение заполнено

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

'admin_login' => [new NotEmpty()],

Пустыми считаются null, пустая строка, строка из одних пробелов, пустой массив и false. Ноль (0, 0.0, '0') пустым не считается.

StringLength — длина строки

// От 2 до 50 символов
'name' => [new StringLength(min: 2, max: 50)],

// Не короче 6 символов
'password' => [new StringLength(min: 6)],

// Не длиннее 250 символов, поле можно не заполнять
'meta_keywords' => [new StringLength(max: 250, allowEmpty: true)],

Параметр	Значение по умолчанию	Описание
min	null	минимальная длина
max	null	максимальная длина

Длина считается в символах, а не в байтах. Значение, которое не является строкой (например число), правило отклоняет: если поле объявлено текстовым, оно должно приходить текстом.

EmailAddress — адрес электронной почты

// Проверка формата адреса
'email' => [new EmailAddress()],

// Дополнительно проверить, что домен существует и принимает почту
'email' => [new EmailAddress(checkMxRecord: true)],

Параметр	Значение по умолчанию	Описание
checkMxRecord	false	проверять MX- или A-записи домена (запрос к DNS)

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

Between — значение в диапазоне

Границы включаются в диапазон.

'day'   => [new Between(min: 1, max: 31)],
'year'  => [new Between(min: 1900, max: 3000)],

Значение, которое не является числом, проверку не проходит. Числовая строка ('5') считается числом.

InArray — значение из списка

'sex' => [new InArray(haystack: ['m', 'zh'])],

Параметр	Значение по умолчанию	Описание
haystack	[]	список допустимых значений
strict	false	строгое сравнение (с учётом типа)

По умолчанию сравнение нестрогое, потому что форма присылает строки: значение "1" совпадёт со списком [1, 2]. Если типы важны — например список собирается из перечисления, — включите strict: true.

Identical — значение совпадает с образцом

Сравнение строгое: 1 и '1' — разные значения.

// Флажок согласия должен быть отмечен
'consent_1' => [new Identical(token: '1', message: __('Необходимо принять соглашение'))],

// Поле-ловушка для ботов должно остаться пустым
'website' => [new Identical(token: '', allowEmpty: true)],

Параметр	Описание
token	значение, с которым сравнивают

Captcha — защитный код

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

'code' => [new Captcha(scope: 'feedback')],

Параметр	Значение по умолчанию	Описание
scope	'default'	имя формы, которую защищает капча

Область должна совпадать с той, с которой форма запрашивала задание, иначе ответ будут искать не там. Подробности — в разделе Капча.

Flood — защита от частой отправки

Проверяет, не отправлял ли посетитель сообщение слишком недавно. Значение поля не проверяется, поэтому правило относится к форме целиком.

use Johncms\Validator\ValidationResult;

$rules[ValidationResult::FORM_KEY] = [new Flood()];

Сколько секунд осталось ждать, подставляется в текст сообщения.

Ban — проверка банов посетителя

Тоже правило уровня формы: проверяется посетитель, а не поле.

$rules[ValidationResult::FORM_KEY] = [new Flood(), new Ban(bans: [1, 13])];

Параметр	Значение по умолчанию	Описание
bans	[1]	типы банов, наличие которых запрещает отправку

ModelExists — запись в базе есть

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

'user_id' => [
    new ModelExists(model: User::class, field: 'id'),
],

Параметр	Значение по умолчанию	Описание
model	—	класс модели Eloquent
field	—	поле таблицы, по которому идёт поиск
exclude	null	замыкание, сужающее выборку

ModelNotExists — записи в базе нет

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

// Имя пользователя не занято
'name' => [
    new StringLength(min: 2, max: 20),
    new ModelNotExists(model: User::class, field: 'name'),
],

// Такое же сообщение от этого же посетителя за последние 10 минут — повтор
'message' => [
    new StringLength(min: 4),
    new ModelNotExists(
        model: GuestbookEntry::class,
        field: 'text',
        exclude: function ($query): void {
            $query->where('user_id', $this->user->id)
                ->where('time', '>', time() - 600);
        },
    ),
],

Параметр exclude принимает замыкание, которое получает построитель запроса и добавляет к нему условия. Так правило узнаёт об остальных данных формы — сами правила видят только значение своего поля.

MxRecord — домен принимает почту

Проверяет наличие MX- или A-записи у домена из адреса. Обычно отдельно не нужен: его включает EmailAddress параметром checkMxRecord. Используйте его напрямую, если адрес проверяется по частям.

'email' => [new EmailAddress(), new MxRecord()],

Значение без символа @ правило пропускает молча — о том, что это не адрес, скажет EmailAddress, и два сообщения об одной ошибке под полем не появятся.