Yii2: встроенные валидаторы. Описание, параметры

Обещанный пост про встроенные валидаторы Yii2. Ниже список валидаторов со всеми их параметрами. Пост получился огромным, на примеры меня не хватило. Так что не судите строго :)

Посты по теме:
Примеры правил валидации
Yii2: валидация, правила валидации, встроенные валидаторы
Yii2. Свой валидатор

Boolean

Параметры:

• trueValue: что считать за true. По умолчанию 1;
• falseValue: что считать за false. По умолчанию 0;
• strict: строгая проверка на соответствие значениям trueValue и falseValue (проверка и значения, и типа данных).

Captcha / валидация капчи

Параметры:

• skipOnEmpty: пропускать ли проверку, если поле не заполнено. По умолчанию false;
• caseSensitive: делать ли проверку регистрозависимой. По умолчанию false;
• captchaAction: роут к экшну, в котором происходит рендеринг капчи. По умолчанию 'site/captcha'.

Compare / сравнение со значением атрибута или с константой

Параметры:

• compareAttribute: имя атрибута, с которым будет проводиться сравнение;
• compareValue: значение, с которым будет проводиться сравнение. Если заданы compareAttribute и compareValue, то сравнение будет проводиться с compareValue;
• type: тип данных, по которому будет происходить сравнение. По умолчанию string. 
• Если указан тип string, то значения будут сравниваться, как строки, никакой конвертации данных перед сравнением проводиться не будет. 
• Если указан тип number, то значения будут сравниваться, как числа, при этом строки будут преобразованы в числа перед сравнением.
• operator: оператор сравнения. Возможные значения: ==, ===, !=, !==, >, >=, <, <=. По умолчанию ==.

Date / Datetime/ Time / валидация даты

Валидатор date имеет два наследника: datetime и time, у которых по умолчанию задан параметр type. Параметры:

• type: тип валидатора: date, datetime, time. Этот параметр работает только при установленном расширении intl;
• format: формат даты/времени. Может быть задан любой формат в соответствии с ICU manual или формат, который может быть определен классом Datetime (при этом необходимо использовать префикс 'php:'). По умолчанию формат определен в соответствии с типом на основе класса \yii\i18n\Formatter;
• locale: локаль. Работает только при установленном расширении intl.
• timeZone: часовой пояс. По умолчанию \yii\base\Application::timeZone.
• timestampAttribute: наименование атрибута для получения результата парсинга даты. Если параметр задан, то в случае успешной валидации в этот атрибут модели будет записан результат парсинга даты.
• timestampAttributeFormat: формат для timestampAttribute. Если не установлен, то параметр будет проигнорирован.
• timestampAttributeTimeZone: часовой пояс для timestampAttribute, по умолчанию UTC. Если не установлен, то параметр будет проигнорирован.
• max: максимальная дата. По умолчанию не ограничена. Может быть задана числом (unix timestamp) или строкой (в этом случае к ней будет применен формат, заданный в format, для парсинга даты).
• min: минимальная дата. По умолчанию не ограничена. Может быть задана числом (unix timestamp) или строкой (в этом случае к ней будет применен формат, заданный в format, для парсинга даты).
• tooBig: пользовательское сообщение об ошибке, если дата больше max.
• tooSmall: пользовательское сообщение об ошибке, если дата меньше min.
• maxString: значение максимальной даты для отображения в сообщении об ошибке.
• minString: значение минимальной даты для отображения в сообщении об ошибке.

Default / значение по умолчанию

Это и не валидатор вовсе, а обработчик данных. Устанавливает значение по умолчанию для выбранных атрибутов. Параметры:

• value: это значение или анонимная функция, которая возвращает значение атрибута;
• skipOnEmpty: пропускать ли проверку, если поле не заполнено. По умолчанию false.

Double / Integer / Number / валидация чисел

Валидатор Double является синонимом валидатора Number. Валидатор Integer – это валидатор Number с установленным параметром integerOnly в true. Параметры:

• integerOnly: проверка только на целые числа. По умолчанию false;
• max: ограничение максимального значения;
• min: ограничение минимального значения;
• tooBig: пользовательское сообщение об ошибке, если значение больше max;
• tooSmall: пользовательское сообщение об ошибке, если значение меньше min;
• integerPattern: регулярное выражение для проверки на целое число. По умолчанию '/^\s*[+-]?\d+\s*$/';
• numberPattern: регулярное выражение для проверки на любое число. По умолчанию '/^\s*[-+]?[0-9]*\.?[0-9]+([eE][-+]?[0-9]+)?\s*$/'.

Each / валидация массивов

Этот валидатор проверяет каждый элемент массива на соответствие заданному правилу. Можно сказать, что это примитивная валидация массивов. Параметры:

• rule: массив правил валидации. Описывается в таком же формате, как и метод rules модели, за исключением перечня атрибутов, здесь он отсутствует;
• allowMessageFormRule: использовать ли сообщение об ошибке, составленное по rule. Если опция включена, то сообщение об ошибке, указанное для валидатора, будет отображаться только в том случае, если значение атрибута не является массивом;
• stopOnFirstError: прекращать валидацию при первой ошибке. Если опция отключена, то результатом будет массив ошибок, если включена – одно сообщение об ошибке. По умолчанию true. Опция работает только при вызове validateAttribute, при вызове validateValue опция не работает.

Email / валидация email

Этот валидатор проверяет каждый элемент массива на соответствие заданному правилу. Можно сказать, что это примитивная валидация массивов. Параметры:

• pattern: регулярное выражение для проверки на email. По умолчанию '/^[a-zA-Z0-9!#$%&\'*+\\/=?^_`{|}~-]+(?:\.[a-zA-Z0-9!#$%&\'*+\\/=?^_`{|}~-]+)*@(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?\.)+[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?$/';
• fullPattern: регулярное выражение для проверки на email, которое используется при включенной опции allowName. По умолчанию '/^[^@]*<[a-zA-Z0-9!#$%&\'*+\\/=?^_`{|}~-]+(?:\.[a-zA-Z0-9!#$%&\'*+\\/=?^_`{|}~-]+)*@(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?\.)+[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?>$/';
• allowName: проверять ли наличие имени в email. Например, "John Smith <john.smith@example.com>". По умолчанию false;
• checkDNS: проверять ли на существование домен и наличие записи A или MX. Эта проверка может завершиться неудачно при временных проблемах с DNS, даже если email-адрес существует и письмо отправлено. По умолчанию false;
• enableIDN: учитывать ли IDN (интернационализированные доменные имена). Для использования проверки IDN необходимо установить и включить расширение PHP `intl`, иначе будет выброшено исключение. По умолчанию false.

Exist / валидация на существование связанной модели

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

• targetClass: имя класса ActiveRecord связанной модели;
• targetAttribute: имя атрибута ActiveRecord, которое должно использоваться для проверки существования текущего значения атрибута. Если параметр не установлен, то будет использоваться имя проверяемого атрибута. Также можно использовать массив для проверки наличия нескольких столбцов одновременно. Ключ массива - это имя атрибута со значением для проверки, значение массива - это имя поля базы данных для поиска;
• filter: дополнительный фильтр, который будет применяться к запросу БД, используемому для проверки существования значения атрибута. Это может быть строка или массив, представляющий дополнительное условие запроса, или функция, в которой можно изменить запрос (инстанс Query);
• allowArray: разрешить ли массив в качестве значения атрибута. По умолчанию false;
• targetAttributeJunction: and|or как связаны атрибуты. По умолчанию and.

File / валидация файлов

Проверяет, является ли значение атрибута действительно загруженным файлом. Параметры:

• extensions: массив или строка (разделитель – пробел или запятая) допустимых расширений файлов. Введенные значения чувствительны к регистру. По умолчанию null, что означает – любые расширения допустимы;
• checkExtenstionByMimeType: проверять ли расширение файла по типу MIME. Если расширение MIME отличается от загруженного расширения файла, файл считается недействительным. По умолчанию true;
• mimeTypes: список MIME-типов, которые могут быть загружены. Это может быть массив или строка. Можно использовать маску для обозначения всех типов группы, например: "image/*". Указанные значения чувствительны к регистру. По умолчанию null, что означает – любые типы допустимы;
• minSize: минимальный размер загружаемого файла;
• maxSize: максимальный размер загружаемого файла;
• maxFiles: максимальное число загруженных файлов. Если установить 0, то лимит не ограничен. При установке этого параметра стоит проверить настройку php max_file_uploads. По умолчанию 1;
• message: сообщение об ошибке, если файл не был загружен корректно;
• uploadRequired: сообщение об ошибке, если файл не был загружен;
• tooBig: пользовательское сообщение об ошибке, если размер файла больше maxSize;
• tooSmall: пользовательское сообщение об ошибке, если размер файла меньше minSize;
• tooMany: пользовательское сообщение об ошибке, если число загруженных файлов больше maxFiles;
• wrongExtension: сообщение об ошибке, если файл имеет недопустимое расширение;
• wrongMimeType: сообщение об ошибке, если файл имеет недопустимый MIME-тип;
• skipOnEmpty: если установить параметр в false, то загрузка файла станет обязательной.

Filter / конвертация значений

Еще один валидатор, который не валидатор, а обработчик данных. Он конвертирует значения в соответствии с установленной callback-функцией. Параметры:

• filter: callback-функция, имеющая в качестве параметра текущее значение атрибута и возвращающая измененное значение;
• skipOnArray: пропускать ли обработку, если в качестве значения получен массив. По умолчанию false;
• skipOnEmpty: пропускать ли проверку, если поле не заполнено. По умолчанию false.

Image / валидация изображений

Это наследник валидатора File с дополнительными параметрами:

• notImage: сообщение об ошибке, если загружаемый файл не является изображением;
• minWidth: минимальная ширина в пикселях. Если не задана, то ширина не ограничена;
• maxWidth: максимальная ширина в пикселях. Если не задана, то ширина не ограничена;
• minHeight: минимальная высота в пикселях. Если не задана, то высота не ограничена;
• maxHeight: максимальная высота в пикселях. Если не задана, то высота не ограничена;
• underWidth: сообщение об ошибке, если ширина изображения меньше минимальной ширины;
• overWidth: сообщение об ошибке, если ширина изображения больше максимальной ширины;
• underHeight: сообщение об ошибке, если высота изображения меньше минимальной высоты;
• overHeight: сообщение об ошибке, если высота изображения больше максимальной высоты.

In / проверка, что значение входит в список допустимых

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

• range: список (массив/Traversable/Closure) допустимых значений атрибута или анонимная функция, которая возвращает такой список;
• strict: строгое сравнение (проверка и значения, и типа данных). По умолчанию false;
• not: следует ли инвертировать логику проверки. По умолчанию false;
• allowArray: разрешить ли массив в качестве значения атрибута. По умолчанию false.

Match / проверка на совпадение с регулярным выражением

Параметры:

• pattern: регулярное выражение;
• not: следует ли инвертировать логику проверки. По умолчанию false.

Required / валидация обязательных полей

Параметры:

• skipOnEmpty: пропускать ли проверку, если поле не заполнено. По умолчанию false;
• requiredValue: значение, которое должен иметь атрибут. Если задано null, валидатор будет проверять, что указанный атрибут не пуст. Если в параметре задано значение, которое не является нулевым, валидатор будет проверять, что значение атрибута совпадает с этим значением;
• strict: строгое сравнение (проверка и значения, и типа данных) между значением атрибута и requiredValue. По умолчанию false. Если установлен в true, то оба значения и типы должны совпадать. Если false, то только значения должны совпадать. ВАЖНО! Когда requiredValue=null
• и strict=true, валидатор проверяет, является ли значение атрибута нулевым;
• и strict=false, валидатор вызовет isEmpty, чтобы проверить, пусто ли значение атрибута;
• message: пользовательское сообщение об ошибке.

Safe / без валидации

Фиктивный валидатор, основная цель которого – отметить атрибуты, которые должны быть безопасными для массового присвоения.
Массовое присвоение – это любая загрузка данных из формы в модель.

$model->attributes = Yii::$app->request->post();
$model->load(Yii::$app->request->post());
$model->setAttributes(Yii::$app->request->post());

Мы передаем в модель массив, а модель уже сама разбирается, какое значение какому атрибуту присвоить. При этом не каждый атрибут модели можно переопределять таким образом, например, идентификаторы должны быть неизменны. То есть идентификатор должен остаться небезопасным атрибутом.
Именно для этого и нужен валидатор safe – чтобы отметить атрибуты, для которых не требуется валидация, но которые должны быть при этом меняться.

String / валидация строк

Параметры:

• length: ограничения длины проверяемого значения. Можно указать в одной из следующих форм:
• целое число: точная длина;
• массив из одного элемента: минимальная длина. Например, [8] перезапишет min, если он задан.
• массив из двух элементов: минимальная и максимальная длины. Например, [8, 128] перезапишет значения min и max, если они заданы;
• max: максимальная длина;
• min: минимальная длина;
• message: пользовательское сообщение об ошибке, если значение атрибута не является строкой;
• tooShort: пользовательское сообщение об ошибке, если длина строки меньше min;
• tooLong: пользовательское сообщение об ошибке, если длина строки больше max;
• notEqual: пользовательское сообщение об ошибке, если длина строки не равна length.
• encoding: кодировка строки, например, UTF-8.

Trim / обрезка пробелов

Это наследник валидатора Filter с предустановленными параметрами:

[
    'filter' => 'trim',
    'skipOnArray' => true,
]

Unique / проверка на уникальность

Валидатор проверяет, является ли значение атрибута уникальным в столбце таблицы БД, определенном параметрами targetClass и targetAttribute.

// a1 должен быть уникальным
['a1', 'unique']
// a1 должен быть уникальным, но для проверки уникальности значения a1 используется a2
['a1', 'unique', 'targetAttribute' => 'a2']
// a1 и a2 должны быть уникальными и они оба возвращают сообщения об ошибках
[['a1', 'a2'], 'unique', 'targetAttribute' => ['a1', 'a2']]
// a1 и a2 должны быть уникальными, но только a1 возвращает сообщение об ошибке
['a1', 'unique', 'targetAttribute' => ['a1', 'a2']]
// a1 должен быть уникальным, для проверки уникальности используются a2 и a3 (при этом для a3 проверяется значение a1)
['a1', 'unique', 'targetAttribute' => ['a2', 'a1' => 'a3']]

Параметры:

• targetClass: имя класса ActiveRecord модели, который должен использоваться для проверки уникальности текущего значения атрибута. Если параметр не установлен, то будет использоваться текущий класс;
• targetAttribute: имя атрибута ActiveRecord, которое должно использоваться для проверки уникальности текущего значения атрибута. Если параметр не установлен, то будет использоваться имя проверяемого атрибута. Также можно использовать массив для проверки наличия нескольких столбцов одновременно. Значения массива - это атрибуты, которые будут использоваться для проверки уникальности, в то время как ключи массива являются атрибутами, значения которых должны быть проверены;
• filter: дополнительный фильтр, который будет применяться к запросу БД, используемому для проверки уникальности значения атрибута. Это может быть строка или массив, представляющий дополнительное условие запроса, или функция, в которой можно изменить запрос (инстанс Query);
• message: пользовательское сообщение об ошибке;
• targetAttributeJunction: and|or как связаны атрибуты. По умолчанию and.

Url / валидация url

Параметры:

• pattern: регулярное выражение. По умолчанию '/^{schemes}:\/\/(([A-Z0-9][A-Z0-9_-]*)(\.[A-Z0-9][A-Z0-9_-]*)+)(?::\d{1,5})?(?:$|[?\/#])/i';
• validScheme: список допустимых протоколов. По умолчанию ['http', 'https'];
• defaultScheme: протокол по умолчанию. Если значение атрибута не содержит протокол, то протокол по умолчанию будет добавлен к нему (то есть значение атрибута изменится). По умолчанию null, то есть URL должен содержать протокол;
• enableIDN: учитывать ли IDN (интернационализированные доменные имена). Для использования проверки IDN необходимо установить и включить расширение PHP `intl`, иначе будет выброшено исключение. По умолчанию false.