Merge pull request #4869 from prosophist/feature

docs/guide-ru/tutorial-core-validators.md

+Встроенные валидаторы
+===============
+
+Yii предоставляет встроенный набор часто используемых валидаторов, расположенных, в первую очередь,
+в пространстве имен `yii\validators`. Вместо того, чтобы использовать длинные имена классов валидаторов,
+вы можете использовать *псевдонимы*, чтобы указать на использование этих валидаторов.
+Например, вы можете использовать псевдоним `required`, чтобы сослаться на класс [[yii\validators\RequiredValidator]]:
+
+```php
+public function rules()
+{
+    return [
+        [['email', 'password'], 'required'],
+    ];
+}
+```
+
+Все поддерживаемые псевдонимы валидаторов можно увидеть в свойстве [[yii\validators\Validator::builtInValidators]].
+
+Ниже мы опишем основные способы использования и свойства всех встроенных валидаторов.
+
+## [[yii\validators\BooleanValidator|boolean]] <a name="boolean"></a>
+
+```php
+[
+    // Проверяет 'selected' на равенство 0 или 1, без учета типа данных
+    ['selected', 'boolean'],
+
+    // Проверяет, что "deleted" - это тип данных boolean и содержит true или false
+    ['deleted', 'boolean', 'trueValue' => true, 'falseValue' => false, 'strict' => true],
+]
+```
+
+Этот валидатор проверяет, что второе значение является *boolean*.
+
+- `trueValue`: значение, соответствующее *true*. По умолчанию - `'1'`.
+- `falseValue`: значение, соответствующее *false*. По умолчанию - `'0'`.
+- `strict`: должна ли проверка учитывать соответствие типов данных `trueValue` или `falseValue`. По умолчанию - `false`.
+
+> Примечание: Из-за того, что как правило данные, полученные из HTML-форм, представляются в виде строки, обычно вам стоит
+оставить свойство [[yii\validators\BooleanValidator::strict|strict]] равным false.
+
+
+## [[yii\captcha\CaptchaValidator|captcha]] <a name="captcha"></a>
+
+```php
+[
+    ['verificationCode', 'captcha'],
+]
+```
+Этот валидатор обычно используется вместе с [[yii\captcha\CaptchaAction]] и [[yii\captcha\Captcha]], чтобы
+убедиться, что данные в инпуте соответствуют верификационному коду, отображенному с помощью виджета
+[[yii\captcha\Captcha|CAPTCHA]].
+
+- `caseSensitive`: необходимо ли учитывать чувствительность к регистру при сравнении. По умолчанию - false.
+- `captchaAction`: [маршрут](structure-controllers.md#routes), соответствующий
+  [[yii\captcha\CaptchaAction|CAPTCHA action]], который рендерит изображение с *CAPTCHA*. По умолчанию - `'site/captcha'`.
+- `skipOnEmpty`: может ли валидация быть пропущена, если *input* пустой. По умолчанию - false,
+  что означает, что *input* обязателен.
+
+
+## [[yii\validators\CompareValidator|compare]] <a name="compare"></a>
+
+```php
+[
+    // проверяет, является ли значение атрибута "password" таким же, как "password_repeat"
+    ['password', 'compare'],
+
+    // проверяет, что возраст больше или равен 30
+    ['age', 'compare', 'compareValue' => 30, 'operator' => '>='],
+]
+```
+
+Этот валидатор сравнивает значение указанного атрибута с другим, чтобы удостовериться, что их отношение
+соответствует описанному в свойстве `operator`.
+
+- `compareAttribute`: имя атрибута, с которым нужно сравнить значение. Когда валидатор используется
+  для проверки атрибута, значением по умолчанию для этого свойства будет имя этого же атрибута
+  с суффиксом `_repeat`. Например, если проверяющийся атрибут - `password`,
+  то значение свойства по умолчанию будет `password_repeat`.
+- `compareValue`: постоянное значение, с которым будут сравниваться входящие данные. Когда одновременно указаны
+   это свойство и `compareAttribute`, это свойство получит приоритет.
+- `operator`: оператор сравнения. По умолчанию `==`, что означает проверку на эквивалентность входящих данных и в
+  `compareAttribute`, и в `compareValue`. Поддерживаются следующие операторы:
+     * `==`: проверяет два значения на эквивалентность. Сравнение не учитывает тип данных.
+     * `===`: проверяет два значения на эквивалентность. Сравнение строгое и учитывает тип данных.
+     * `!=`: проверяет, что два значения не эквивалентны. Сравнение не учитывает тип данных.
+     * `!==`: проверяет, что два значения не эквивалентны. Сравнение строгое и учитывает тип данных.
+     * `>`: проверяет, что валидируемое значение больше, чем то, с которым происходит сравнение.
+     * `>=`: проверяет, что валидируемое значение больше или равно тому, с которым происходит сравнение.
+     * `<`: проверяет, что валидируемое значение меньше, чем то, с которым происходит сравнение.
+     * `<=`: проверяет, что валидируемое значение меньше или равно тому, с которым происходит сравнение.
+
+
+## [[yii\validators\DateValidator|date]] <a name="date"></a>
+
+```php
+[
+    [['from', 'to'], 'date'],
+]
+```
+Этот валидатор проверяет соответствие входящих данных форматам *date*, *time* или *datetime*.
+Опционально, он может конвертировать входящее значение в UNIX timestamp и сохранить в атрибуте,
+описанном здесь: [[yii\validators\DateValidator::timestampAttribute|timestampAttribute]].
+
+- `format`: формат даты/времени, согласно которому должна быть сделана проверка. Чтобы узнать больше о формате
+  строки, пожалуйста, посмотрите [руководство PHP по date_create_from_format()](http://www.php.net/manual/ru/datetime.createfromformat.php)
+  Значением по умолчанию является `'Y-m-d'`.
+- `timestampAttribute`: имя атрибута, которому этот валидатор может передать UNIX timestamp, конвентированный
+  из строки даты/времени.
+
+
+## [[yii\validators\DefaultValueValidator|default]] <a name="default"></a>
+
+```php
+[
+    // установить null для "age" в качестве значения по умолчанию
+    ['age', 'default', 'value' => null],
+
+    // установить "USA" в качестве значения по умолчанию для "country"
+    ['country', 'default', 'value' => 'USA'],
+
+    // установить в "from" и "to" дату 3 дня и 6 дней от сегодняшней, если они пустые
+    [['from', 'to'], 'default', 'value' => function ($model, $attribute) {
+        return date('Y-m-d', strtotime($attribute === 'to' ? '+3 days' : '+6 days'));
+    }],
+]
+```
+
+Этот валидатор не проверяет данные. Вместо этого он присваивает значения по умолчанию проходящим проверку
+атрибутам, если они пусты.
+
+- `value`: значение по умолчанию или функция обратного вызова, которая возвращает значение по умолчанию,
+  которое будет присвоено проверяемому атрибуту, если он пустой. Функция обратного вызова должна выглядеть так:
+
+```php
+function foo($model, $attribute) {
+    // ... вычисление $value ...
+    return $value;
+}
+```
+
+> Информация: Как определить, является значение пустым или нет, более подробно описано в отдельной статье
+  в секции [Пустые значения](input-validation.md#handling-empty-inputs).
+
+
+## [[yii\validators\NumberValidator|double]] <a name="double"></a>
+
+```php
+[
+    // проверяет, является ли "salary" числом типа double
+    ['salary', 'double'],
+]
+```
+
+Этот валидатор проверяет, что входящее значение является корректным *double* числом. Он идентичен
+валидатору [number](#number). (Прим. пер.: корректным float числом).
+
+- `max`: верхний лимит (включительно) для значений. Если не установлен, значит, валидатор не будет проверять верхний лимит.
+- `min`: Нижний лимит (включительно) для значений. Если не установлен, валидатор не будет проверять нижний лимит.
+
+
+## [[yii\validators\EmailValidator|email]] <a name="email"></a>
+
+```php
+[
+    // проверяет, что "email" - это корректный email-адрес
+    ['email', 'email'],
+]
+```
+Валидатор проверяет, что значение входящих данных является корректным email-адресом.
+
+- `allowName`: можно ли передавать в атрибут имя (пример: `John Smith <john.smith@example.com>`). По умолчанию - false.
+- `checkDNS`, проверяет, существует ли доменное имя для введенного адреса (и A, и MX запись).
+  Учтите, что проверка может закончится неудачей, что может быть вызвано временными проблемами с DNS, даже если
+  email-адрес корректен. По умоланию - false.
+- `enableIDN`, нужно ли учитывать IDN (многоязычные доменные имена). По умолчанию - false. Учтите, что для использования
+  IDN-валидации вам нужно установить и включить PHP расширение `intl`, иначе будет выброшено исключение.
+
+
+## [[yii\validators\ExistValidator|exist]] <a name="exist"></a>
+
+```php
+[
+    // a1 должно существовать в столбце, который представляется атрибутом "a1"
+    ['a1', 'exist'],
+
+    // a1 должно существовать, но его значение будет использовать a2 для проверки существования
+    ['a1', 'exist', 'targetAttribute' => 'a2'],
+
+    // и a1, и a2 должны существовать, в противном случае оба атрибута будут возвращать ошибку
+    [['a1', 'a2'], 'exist', 'targetAttribute' => ['a1', 'a2']],
+
+    // и a1, и a2 должны существовать, но только атрибут a1 будет возвращать ошибку
+    ['a1', 'exist', 'targetAttribute' => ['a1', 'a2']],
+
+    // a1 требует проверки существования a2 и a3 (используя значение a1)
+    ['a1', 'exist', 'targetAttribute' => ['a2', 'a1' => 'a3']],
+
+    // a1 должен существовать. Если a1 - массив, то каждый его элемент должен существовать
+    ['a1', 'exist', 'allowArray' => true],
+]
+```
+
+Этот валидатор ищет входящие данные в столбце таблицы. Он работает только с атрибутами
+модели [Active Record](db-active-record.md). Он поддерживает проверку и одного столбца, и нескольких.
+
+- `targetClass`: имя класса [Active Record](db-active-record.md), который должен быть использован для проверки
+  входящего значения. Если не установлен, будет использован класс текущей модели.
+- `targetAttribute`: имя атрибута в `targetClass` который должен быть использован для проверки существования
+  входящего значения. Если не установлен, будет использовано имя атрибута, который проверяется в данный момент.
+  Вы можете использовать массив для валидации нескольких столбцов одновременно. Значения массива являются атрибутами,
+  которые будут использованы для проверки существования, тогда как ключи массива будут являться атрибутами, чьи значения
+  будут проверены. Если ключ и значения одинаковы, вы можете указать только значение.
+- `filter`: дополнительный фильтр, который будет добавлен к запросу в базу данных для проверки на существование значения.
+  Это может быть строка или массив, представляющие дополнительные условия в запросе (подробнее о формате
+  значений запроса: [[yii\db\Query::where()]]), или анонимная функция с сигнатурой `function ($query)`,
+  где `$query` - это [[yii\db\Query|Query]] объект, который вы можете модифицировать в функции.
+- `allowArray`: разрешать ли значению быть массивом. По умолчанию - false. Если свойство установлено в true
+  и тип входящих данных - массив, тогда каждый его элемент должен существовать в соответствующем столбце таблицы.
+  Помните, что это свойство не может быть установлено в true, если вы валидируете несколько столбцов, передавая
+  их в `targetAttribute` как массив.
+
+
+## [[yii\validators\FileValidator|file]] <a name="file"></a>
+
+```php
+[
+    // проверяет, что "primaryImage" - это загруженное изображение в формате PNG, JPG или GIF
+    // размер файла должен быть меньше 1MB
+    ['primaryImage', 'file', 'extensions' => ['png', 'jpg', 'gif'], 'maxSize' => 1024*1024*1024],
+]
+```
+
+Этот валидатор проверяет, что input является корректным загруженным файлом.
+
+- `extensions`: список имен расширений, которые допустимы для загрузки. Это также может быть или массив, или
+  строка, содержащая имена файловых расширений, разделенных пробелом или запятой (пр.: "gif, jpg").
+  Имя расширения не чувствительно к регистру. По умолчанию - null, что значит, что все имена файловых расширений
+  допустимы.
+- `mimeTypes`: список MIME-типов которые допустимы для загрузки. Это может быть или массив, или строка,
+  содержащая MIME-типы файлов, разделенные пробелом или запятой (пример: "image/jpeg, image/png").
+  Имена mime-типов не чувствительны к регистру. По умолачанию - null, что значит, что допустимы все MIME-типы.
+- `minSize`: минимальный размер файла в байтах, разрешенный для загрузки. По умолчанию - null, что значит, что нет
+  минимального лимита.
+- `maxSize`: максимальный размер файла в байтах, разрешенный для загрузки. По умолчанию - null, что значит, что нет
+  максимального лимита.
+- `maxFiles`: максимальное количество файлов, которое может быть передано в атрибут. По умолчанию 1, что значит, что
+  input должен быть файлом в единственном экземпляре. Если больше, чем 1, то атрибут должен быть массивом,
+  состоящим из не более, чем `maxFiles` загруженных файлов.
+- `checkExtensionByMimeType`: нужно ли проверять расширение файла исходя из его MIME-типа. Если они не соответствуют
+  друг другу, то файл будет считаться некорректным. По умолчанию - true, то есть проверка будет произведена.
+
+`FileValidator` используется вместе с [[yii\web\UploadedFile]]. Пожалуйста, посмотрите раздел
+[Загрузка файлов](input-file-upload.md) для более полного понимания загрузки и проверки файлов.
+
+
+## [[yii\validators\FilterValidator|filter]] <a name="filter"></a>
+
+```php
+[
+    // обрезает пробелы вокруг "username" и "email"
+    [['username', 'email'], 'filter', 'filter' => 'trim', 'skipOnArray' => true],
+
+    // нормализует значение "phone"
+    ['phone', 'filter', 'filter' => function ($value) {
+        // нормализация значения происходит тут
+        return $value;
+    }],
+]
+```
+
+Этот валидатор не проверяет данные. Вместо этого он применяет указанный фильтр к входящему значению и
+присваивает результат применения фильтра атрибуту.
+
+- `filter`: PHP-callback, осуществляющий фильтрацию. Это может быть глобальная php функция, анонимная функция
+  и т.д. Функция должна выглядеть как `function ($value) { return $newValue; }`. Это свойство обязательно должно
+  быть установлено.
+- `skipOnArray`: нужно ли пропускать валидацию, если входящим значением является массив. По умолчанию - false.
+  Помните, что если фильтр не может принимать массив, вы должны установить это значение в true. Иначе могут
+  произойти различные ошибки PHP.
+
+> Трюк: Если вы хотите удалить пробелы вокруг значений атрибута, вы можете использовать валидатор [trim](#trim).
+
+## [[yii\validators\ImageValidator|image]] <a name="image"></a>
+
+```php
+[
+    // проверяет, что "primaryImage" - это валидное изображение с указанными размерами
+    ['primaryImage', 'image', 'extensions' => 'png, jpg',
+        'minWidth' => 100, 'maxWidth' => 1000,
+        'minHeight' => 100, 'maxHeight' => 1000,
+    ],
+]
+```
+
+Этот валидатор проверяет, что входящие данные являются корректным файлом изображения. Он расширяет [file](#file)
+валидатор и наследует все его свойства. Кроме того, он поддерживает следующие дополнительные свойства, специфичные
+для валидации изображений:
+
+- `minWidth`: минимальныя ширина изображения. По умолчанию null, что значит, что нет нижнего лимита.
+- `maxWidth`: максимальная ширина изображения. По умолчанию null, что значит, что нет верхнего лимита.
+- `minHeight`: минимальныя высота изображения. По умолчанию null, что значит, что нет нижнего лимита.
+- `maxHeight`: максимальная высота изображения. По умолчанию null, что значит, что нет верхнего лимита.
+
+
+## [[yii\validators\RangeValidator|in]] <a name="in"></a>
+
+```php
+[
+    // проверяет, что значение "level" равно 1, 2 или 3
+    ['level', 'in', 'range' => [1, 2, 3]],
+]
+```
+
+Этот валидатор проверяет, что вхоящее значение соответствует одному из значений, указанных в `range`.
+
+- `range`: список значений, с которыми будет сравниваться входящее значение.
+- `strict`: должно ли сравнение входящего значения со списком значений быть строгим (учитывать тип данных).
+  По умолчанию false.
+- `not`: должен ли результат проверки быть инвертирован. По умолчанию - false. Если свойство установлено в true,
+  валидатор проверяет, что входящее значение НЕ соответсвует ни одному из значений, указанных в `range`.
+- `allowArray`: устанавливает, допустимо ли использовать массив в качестве входных данных. Если установлено в true
+  и входящие данные являются массивом, для каждого элемента входящего массива должно быть найдено соответствие в
+  `range`.
+
+
+## [[yii\validators\NumberValidator|integer]] <a name="integer"></a>
+
+```php
+[
+    // проверяет "age" на то, что это integer значение
+    ['age', 'integer'],
+]
+```
+
+Проверяет, что входящее значение является integer значением.
+
+- `max`: верхний лимит (включительно) для числа. Если не установлено, валидатор не будет проверять верхний лимит.
+- `min`: нижний лимит (включительно) для числа. Если не установлено, валидатор не будет проверять нижний лимит.
+
+
+## [[yii\validators\RegularExpressionValidator|match]] <a name="match"></a>
+
+```php
+[
+    // проверяет, что "username" начинается с буквы и содержит только буквенные символы,
+    // числовые символы и знак подчеркивания
+    ['username', 'match', 'pattern' => '/^[a-z]\w*$/i']
+]
+```
+
+Этот валидатор проверяет, что входящее значение совпадает с указанным регулярным выражением.
+
+- `pattern`: регулярное выражение, с которым должно совпадать входящее значение. Это свойство должно быть установлено,
+  иначе будет выброшено исключение.
+- `not`: инвертирует регулярное выражение. По умолчанию false, что значит, что валидация будет успешна,
+   только если входящее значение совпадают с шаблоном. Если установлено в true, валидация будет успешна,
+   только если входящее значение НЕ совпадает с шаблоном.
+
+
+## [[yii\validators\NumberValidator|number]] <a name="number"></a>
+
+```php
+[
+    // проверяет, является ли "salary" числом
+    ['salary', 'number'],
+]
+```
+
+Этот валидатор проверяет, являются ли входящие значения числовыми. Он эквивалентен валидатору [double](#double).
+
+- `max`: верхний лимит (включительно) для числа. Если не установлено, валидатор не будет проверять верхний лимит.
+- `min`: нижний лимит (включительно) для числа. Если не установлено, валидатор не будет проверять нижний лимит.
+
+
+## [[yii\validators\RequiredValidator|required]] <a name="required"></a>
+
+```php
+[
+    // проверяет, являются ли "username" и "password" не пустыми
+    [['username', 'password'], 'required'],
+]
+```
+
+Этот валидатор проверяет, являются ли входящие значения не пустыми.
+
+- `requiredValue`: желаемое значение, которому должны соответствовать проверямые данные. Если не установлено,
+  это значит, что данные должны быть не пусты.
+- `strict`: учитывать или нет соответствие типу данных при валидации (строгое сравнение).
+  Если `requiredValue` не установлено, а это свойство установлено в true, валидатор проверит, что входящее значение
+  строго не соответствует null; если свойство установлено в false, валидатор будет проверять значение на пустоту с
+  приведением типов.
+  Если `requiredValue` установлено, сравнение между входящими данными и `requiredValue` будет также учитывать тип
+  данных, если это свойство установлено в true.
+
+> Информация: как определить, является ли значение пустым или нет, подробнее рассказывается
+  в секции [Пустые значения](input-validation.md#handling-empty-inputs).
+
+
+## [[yii\validators\SafeValidator|safe]] <a name="safe"></a>
+
+```php
+[
+    // обозначает "description" как safe атрибут
+    ['description', 'safe'],
+]
+```
+
+Этот валидатор не проверяет данные. Вместо этого он указывает, что атрибут является
+[безопасным атрибутом](structure-models.md#safe-attributes).
+
+
+## [[yii\validators\StringValidator|string]] <a name="string"></a>
+
+```php
+[
+    // проверяет, что "username" это строка с длиной от 4 до 24 символов
+    ['username', 'string', 'length' => [4, 24]],
+]
+```
+
+Этот валидатор проверяет, что входящее значение - это корректная строка с указанной длиной.
+
+- `length`: описывает длину для строки, проходящей валидацию. Может быть определен следующими
+   способами:
+     * числом: точная длина, которой должна соответствовать строка;
+     * массив с одним элементом: минимальная длина входящей строки (напр.: `[8]`). Это перезапишет `min`.
+     * массив с двумя элементами: минимальная и максимальная длина входящей строки (напр.: `[8, 128]`).
+     Это перезапишет и `min`, и `max`.
+- `min`: минимальная длина входящей строки. Если не установлено, то не будет ограничения на минимальную длину.
+- `max`: максимальная длина входящей строки. Если не установлено, то не будет ограничения на максимальную длину.
+- `encoding`: кодировка входящей строки. Если не установлено, будет использовано значение из
+  [[yii\base\Application::charset|charset]], которое по умолчанию установлено в `UTF-8`.
+
+
+## [[yii\validators\FilterValidator|trim]] <a name="trim"></a>
+
+```php
+[
+    // обрезает пробелы вокруг "username" и "email"
+    [['username', 'email'], 'trim'],
+]
+```
+
+Этот валидатор не производит проверки данных. Вместо этого он будет обрезать пробелы вокруг входящих данных.
+Помните, что если входящие данные являются массивом, то они будут проигнорированы этим валидатором.
+
+
+## [[yii\validators\UniqueValidator|unique]] <a name="unique"></a>
+
+```php
+[
+    // a1 должен быть уникальным в столбце, который представляет "a1" атрибут
+    ['a1', 'unique'],
+
+    // 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
+    // (используя значение a1)
+    ['a1', 'unique', 'targetAttribute' => ['a2', 'a1' => 'a3']],
+]
+```
+
+Этот валидатор проверяет входящие данные на уникальность в столбце таблицы. Он работает только с
+атрибутами модели [Active Record](db-active-record.md). Он поддерживает проверку либо одного столбца,
+либо нескольких.
+
+- `targetClass`: имя класса [Active Record](db-active-record.md), который должен быть использован
+  для проверки значения во входящих данных. Если не установлен, будет использован класс модели, которая
+  в данный момент проходит проверку.
+- `targetAttribute`: имя атрибута в `targetClass`, который должен быть использован для проверки на
+  уникальность входящего значения. Если не установлено, будет использован атрибут, проверяемый
+  в данный момент.
+  Вы можете использовать массив для проверки нескольких столбцов таблицы на уникальность. Значения массива -
+  это атрибуты, которые будут использованы для валидации, а ключи массива - это атрибуты, которые предоставляют
+  данные для валидации. Если ключ и значение одинаковые, вы можете указать только значение.
+- `filter`: дополнительный фильтр, который можно присоединить к запросу в БД, чтобы использовать его при
+  проверке значения на уникальность. Это может быть строка или массив, представляющие дополнительные условия для запроса
+  (см. [[yii\db\Query::where()]] о формате условий в запросе), или анонимная функция вида `function ($query)`,
+  где `$query` это объект [[yii\db\Query|Query]], который вы можете изменить в функции.
+
+
+## [[yii\validators\UrlValidator|url]] <a name="url"></a>
+
+```php
+[
+    // Проверяет, что "website" является корректным URL. Добавляет http:// к атрибуту "website".
+    // если у него нет URI схемы
+    ['website', 'url', 'defaultScheme' => 'http'],
+]
+```
+
+Этот валидатор проверяет, что входящее значение является корректным URL.
+
+- `validSchemes`: массив с указанием на URI-схему, которая должна считаться корректной. По умолчанию
+  `['http', 'https']`, что означает, что и `http`, и `https` URI будут считаться корректными.
+- `defaultScheme`: схема URI, которая будет присоединена к входящим данным, если в них отсутствует URI-схема.
+  По умолчанию null, что значит, что входящие данные не будут изменены.
+- `enableIDN`: должна ли валидация учитывать IDN (интернационализованные доменные имена).
+  По умолчанию - false. Учтите, что для того, чтобы IDN валидация работала корректно, вы должны установить `intl`
+  PHP расширение, иначе будет выброшено исключение.
+