Yii. Валидация. Сценарии

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

Правила валидации полей модели описываются в rules(). Каждое правило представлено в виде

array(
    'список полей модели',
    'валидатор',
    'on'=>'имя сценария',
    'except'=>'имя сценария',
    'message'=>'сообщение об ошибке',
    …параметры валидации…
);

Думаю, в этой записи все предельно ясно. Мы указываем список полей модели, для которых будет применяться данный валидатор для сценариев, указанных в on, и не будет применяться для сценариев, указанных в except. Возможность исключать отдельные правила появилась, начиная с версии 1.1.11.

Список сценариев в параметрах on и except может быть задан двумя способами: строкой или массивом.

'on'=>array('update', 'insert'),
'except'=>'ignore, this, scenarios, at-all',

Сценарии по умолчанию

При создании модели (new CActiveRecord) устанавливается сценарий insert.
При загрузке модели (все производные от find и последующем сохранении - update CActiveRecord) устанавливается сценарий update.
Правила валидации, в которых не указаны сценарии, срабатывают при любых сценариях.
Чтобы валидация модели проходила по нужному сценарию (если это не сценарий по умолчанию), необходимо установить этот сценарий.

$modelA = User::model()->findByPk(1); // $model->scenario = 'update'
$modelB = new User();                 // $model->scenario = 'insert'
$modelB->scenario = 'light';          // custom scenario
if ($modelB->validate()) {            // will only apply rules of the "light" scenario
}

Откуда берутся валидаторы

Yii ищет валидатор в определённом порядке:

1. Метод модели с тем же именем, что указано в массиве. Validator может быть именем метода в классе модели данных. В таком случае метод проверки оформляется следующим образом:

   public function ValidatorName($attribute,$params) {
      …
   }
   

2. Встроенный валидатор Yii, унаследованный от CValidator. Ниже приведен полный список предопределенных псевдонимов валидаторов.
3. Путь или псевдоним, указывающий на свой валидатор.
   Можно указать Validator в качестве имени класса. В этом случае для проверки данных в момент применения правила создается экземпляр класса проверки. Дополнительные параметры в правиле используются для инициализации значений атрибутов экземпляра. Класс проверки должен быть производным классом от CValidator.

Предопределенные валидаторы Yii

boolean (CBooleanValidator)

проверяет значение атрибута на соответствие либо свойству trueValue, либо свойству falseValue

allowEmpty	может ли значение равняться null или быть пустым
falseValue	значение, представляющее статус false. По умолчанию - '0'
trueValue	значение, представляющее статус true. По умолчанию - '1'
strict	является ли сравнение строгим: должны совпадать не только значения, но и их тип

captcha (CCaptchaValidator)

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

allowEmpty	может ли значение равняться null или быть пустым
captchaAction	идентификатор действия, которое генерирует изображение капчи. По умолчанию - 'captcha', т.е. действие 'captcha', определенное в текущем контроллере. Также это может быть маршрут, содержащий идентификаторы контроллера и действия
caseSensitive	должно ли сравнение быть регистрозависимым. По умолчанию - false

compare (CCompareValidator)

сравнивает значение определенного атрибута с другим значением на равенство.
Сравниваемое значение может быть значением другого атрибута (определенного свойством compareAttribute) или постоянным значением (определенным свойством compareValue).
Если определены оба свойства, преимущество имеет второе.
Если не определено ни одно из них, атрибут будет сравнен с другим атрибутом с именем вида "ATTRNAME_repeat", где ATTRNAME - имя исходного атрибута.
Начиная с версии 1.0.8, валидатор поддерживает различные операторы сравнения. Ранее сравнивалось только равенство двух значений

allowEmpty	может ли значение равняться null или быть пустым
compareAttribute	имя атрибута, с которым сравнивается исходный атрибут
compareValue	постоянное значение, с которым сравнивается атрибут
operator	оператор сравнения. По умолчанию - '='. Допустимы следующие операторы: '=' или '==': равенство двух значений. Если свойство strict установлено в true, сравнение будет строгим (т.е. тип значения также будет проверен). '!=': проверка того, что два значения не равны. Если свойство strict установлено в true, сравнение будет строгим (т.е. тип значения также будет проверен). '>': валидируемое значение больше значения, с которым происходит сравнение. '>=': валидируемое значение больше или равно значения, с которым происходит сравнение. '<': валидируемое значение меньше значения, с которым происходит сравнение. '<=': валидируемое значение меньше или равно значения, с которым происходит сравнение.
strict	является ли сравнение строгим: должны совпадать не только значения, но и их тип

date (CDateValidator)

проверяет соответствие атрибута дате, времени или временной отметке. Установкой свойства format можно определять формат значения даты. Если переданное значение даты не соответствует данному формату, атрибут считается неверным

allowEmpty	может ли значение равняться null или быть пустым
format	шаблон формата, которому должно соответствовать значение даты. Может быть строкой или массивом, представляющим несколько форматов. По умолчанию - 'MM/dd/yyyy'. Остальные форматы описаны в API CDateTimeParser
timestampAttribute	имя атрибута для получения результата разбора. Если даное свойство не равно null и валидация прошла успешно, атрибут будет заполнен значением результата разбора в виде временной отметки

default (CDefaultValueValidator)

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

setOnEmpty	должно ли значение по умолчанию устанавливаться только при нулевом или пустом значении атрибута. По умолчанию - true. Если установлено в false, атрибут всегда будет связываться со значением по умолчанию, даже если он уже имеет явно присвоенное значение
value	значения по умолчанию, в которые должны быть установлены атрибуты

email (CEmailValidator)

проверяет, что значение атрибута - правильный адрес email

allowEmpty	может ли значение равняться null или быть пустым
allowName	допустимо ли имя в адресе email (например, "Qiang Xue "). По умолчанию - false
checkMX	проверять ли запись MX
checkPort	проверять ли 25-й порт
fullPattern	регулярное выражение, используемое для проверки адреса с именем. Свойство используется только если свойство allowName установлено в true
pattern	регулярное выражение, используемое для проверки адреса без имени

exist (CExistValidator)

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

allowEmpty	может ли значение равняться null или быть пустым
attributeName	имя атрибута ActiveRecord-класса, используемое для поиска значения валидируемого атрибута. По умолчанию - null, т.е. использование имени валидируемого атрибута
caseSensitive	использовать ли регистрозависимую проверку
className	имя ActiveRecord-класса, используемое для поиска валидируемого атрибута. По умолчанию - null, т.е. использование ActiveRecord-класса валидируемого атрибута. Вы можете использовать здесь псевдонимы (и пути) для ссылки на имя класса
criteria	дополнительный критерий запроса. Будет объединен с условием, проверяющим существование значения атрибута в соответствующем столбце таблицы. Данный массив будет использован для создания экземпляра CDbCriteria

file (CFileValidator)

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

foreach($models as $i=>$model)
    $model->attribute = CUploadedFile::getInstance($model, "[$i]attribute");

Запомните, что вы должны использовать метод {@link CUploadedFile::getInstances} для загрузки нескольких файлов.
При использовании CFileValidator с active record-объектами часто используется следующий код:

 if($model->save()) {
    // одиночная загрузка
    $model->attribute->saveAs($path);
    // множественная загрузка
    foreach($model->attribute as $file)
       $file->saveAs($path);
 }

Вы можете использовать CFileValidator для проверки атрибутов файла.

allowEmpty	может ли значение равняться null или быть пустым
maxFiles	максимальное количество файлов
maxSize	максимальный размер в байтах/ По умолчанию - null, т.е. без ограничения. Примечание: максимальный размер также устанавливается свойством 'upload_max_filesize' в файле INI и скрытым полем 'MAX_FILE_SIZE'
mimeTypes	список MIME-типов, разрешенных к загрузке
minSize	минимальный размер в байтах
tooLarge	сообщение об ошибке, выдаваемое если файл слишком большой
tooMany	сообщение, выдаваемое если загружено слишком много файлов
tooSmall	сообщение, выдаваемое если загруженный файл слишком мал
types	список расширений, допустимых для загрузки. Он может быть массивом или строкой, содержащей расширения, разделенные пробелом или запятой (например, "gif, jpg"). Расширения регистронезависимы. По умолчанию - null, т.е. допустимы любые расширения
wrongMimeType	сообщение, выдаваемое если файла с данным MIME-типом загружать нельзя
wrongType	сообщение, выдаваемое если данный тип файла загружать нельзя

filter (CFilterValidator)

преобразовывает валидируемые данные, используя фильтр.
CFilterValidator на самом деле не валидатор, а процессор данных. Он выполняет определенный метод фильтрации над атрибутом и возвращает результат обратно в атрибут. Метод фильтрации должен иметь следующую структуру:

function foo($value) {...return $newValue; }

Многие функции PHP имеют такую структуру (например, trim). Для определения метода фильтрации присвойте свойству filter имя функции.

filter	метод-фильтр

in (CRangeValidator)

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

allowEmpty	может ли значение равняться null или быть пустым
range	список допустимых значений, среди которых должен быть атрибут
strict	является ли сравнение строгим: должны совпадать не только значения, но и их тип
not	инвертировать ли логику валидации. По умолчанию - false. Если установлено в значение true, то значение атрибут не должно находиться в списке значений, определенных свойством range

length (CStringValidator)

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

allowEmpty	может ли значение равняться null или быть пустым
encoding	кодировка строки валидируемого значения (например, 'UTF-8'). Установка данного свойства требует включенного PHP расширения mbstring. Значение данного свойства будет использовано в качестве второго параметра функции mb_strlen(). По умолчанию равно кодировке приложения, т.е., для вычисления длины строки будет использоваться кодировка приложения если доступна функция mb_strlen(), иначе используется функция strlen()
is	точное количество символов
max	максимальное количество символов
min	минимальное количество символов
tooShort	сообщение об ошибке, выдаваемое если количество символов слишком мало
tooLong	сообщение об ошибке, выдаваемое если количество символов слишком велико

match (CRegularExpressionValidator)

проверяет атрибут на соответствие определенному pattern регулярному выражению. Вы можете инвертировать логику валидации при помощи свойства not (доступно с версии 1.1.5)

allowEmpty	может ли значение равняться null или быть пустым
not	инвертировать ли логику проверки. По умолчанию - false. Если установлено в значение true, то регулярное выражение, определенное свойством pattern не должно соответствовать проверяемому значению атрибута
pattern	регулярное выражение

numerical (CNumberValidator)

проверяет, что значение атрибута является числом

allowEmpty	может ли значение равняться null или быть пустым
integerOnly	только целые числа
integerPattern	регулярное выражение для поиска целых чисел
max	максимальное значение
min	минимальное значение
numberPattern	регулярное выражение для поиска чисел
tooBig	сообщение об ошибке, выдаваемое если значение слишком велико
tooSmall	сообщение об ошибке, выдаваемое если значение слишком мало

required (CRequiredValidator)

проверяет, не является ли значение атрибута пустым

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

safe(CSafeValidator)

помечает атрибут безопасным для массового присваивания

type (CTypeValidator)

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

• integer 32-х битные целочисленные знаковые данные.
• float Числа с плавающей точкой двойной точности.
• string Строковые данные.
• array Массив.
• date Дата.
• time Время (доступен с версии 1.0.5).
• datetime Дата и время (доступен с версии 1.0.5).

Для типа date свойство dateFormat будет использоваться для определения того, как разбирать строку даты. Если переданное значение даты не соответствует данному формату, атрибут будет считаться неправильным.
Начиная с версии 1.1.7 существует отдельный валидатор дат CDateValidator. Используйте его для валидации значений дат.

allowEmpty	может ли значение равняться null или быть пустым
dateFormat	формат для валидации дат
datetimeFormat	формат для валидации даты и времени
timeFormat	формат для валидации времени
type	тип данных

unique (CUniqueValidator)

проверяет значение атрибута на уникальность в соответствующей таблице БД

allowEmpty	может ли значение равняться null или быть пустым
attributeName	имя атрибута класса ActiveRecord, используемое для проверки значения
caseSensitive	является ли сравнение регистронезависимым
className	имя класса ActiveRecord, используемого для проверки
criteria	дополнительный критерий запроса
message	пользовательское сообщение об ошибке. Можно использовать маркеры "{attribute}" и "{value}", которые будут заменены реальным именем или значением атрибута соответственно
skipOnError	пропускать ли правило в случае, если для указанного атрибута ошибка уже произошла

unsafe(CUnsafeValidator)

помечает связанные атрибуты как небезопасные так, что они не могут быть присвоены пакетно

url (CUrlValidator)

проверяет, чтобы атрибут был допустимым URL-адресом протоколов http и https

allowEmpty	может ли значение равняться null или быть пустым
defaultScheme	URI-схема по умолчанию. Если входное значение не содержит части со схемой, то схема по умолчанию будет подставлена перед значением (изменив тем самым входное значение). По умолчанию - null, т.е., URL-адрес должен содержать часть со схемой
pattern	регулярное выражение, используемое при валидации. С версии 1.1.7 шаблон может содержать метку {schemes}, заменяемую регулярным выражением, представленным свойством validSchemes
validSchemes	список URI-схем, которые должны считаться валидными. По умолчанию, схемы http и https считаются валидными

Примеры

// имя пользователя — обязательное поле формы
array('username', 'required'),
// длина имени пользователя должна быть от 3 до 12 символов включительно
array('username', 'length', 'min'=>3, 'max'=>12),
// в сценарии регистрации значения полей «password» и «password2» должны быть равны
array('password', 'compare', 'compareAttribute'=>'password2', 'on'=>'register'),
// в сценарии аутентификации поле `password` должно быть проверено на соответствие указанному имени пользователя
array('password', 'authenticate', 'on'=>'login'),

Еще немного о валидации здесь.