Как создать своё правило валидации в Yii
Своё правило валидации в Yii 2 можно объявить методом модели или вынести в отдельный класс. Разберём оба способа на проверке slug и покажем, как учесть пустые значения, сценарии и проверку в браузере.
Когда нужно своё правило валидации
Для обязательного поля используйте required, для обычной проверки по регулярному выражению — match. Своё правило стоит вводить, когда у проверки есть отдельный смысл в приложении. Например, slug страницы должен состоять из строчных латинских букв и цифр, может содержать одиночные дефисы и не должен совпадать с именем служебного маршрута.
Метод модели удобен, если правило относится к одной форме или зависит от её полей. Отдельный класс пригодится, когда тот же контракт нужен в форме создания, админке и импорте. Примеры ниже используют API Yii 2 и синтаксис PHP 8.3–8.5.
Способ 1. Объявите метод-валидатор в модели
Укажите имя публичного метода вторым элементом правила в rules(). Yii передаст ему имя проверяемого атрибута и дополнительные параметры правила. При ошибке вызовите addError() с именем поля и сообщением. Возвращаемое значение метода Yii для этой проверки не использует.
<?php
declare(strict_types=1);
namespace app\models;
use yii\base\Model;
final class PageForm extends Model
{
public mixed $slug = null;
public function rules(): array
{
return [
['slug', 'required'],
['slug', 'validateSlug', 'reserved' => ['admin', 'api']],
];
}
public function validateSlug(string $attribute, array $params): void
{
$value = $this->$attribute;
// Поле формы может прийти массивом, например из slug[].
if (!is_string($value) || strlen($value) > 80
|| preg_match('/\A[a-z0-9]+(?:-[a-z0-9]+)*\z/', $value) !== 1) {
$this->addError($attribute, 'Введите до 80 строчных латинских букв, цифр и одиночных дефисов между ними.');
return;
}
if (in_array($value, $params['reserved'], true)) {
$this->addError($attribute, 'Этот slug зарезервирован.');
}
}
}mixed здесь описывает входное поле формы. При массовом присваивании из запроса типизированное свойство ?string может выбросить TypeError ещё до validate(), если получит массив. Внутри валидатора is_string() сужает тип до строки. Для допустимого ASCII-алфавита длина в байтах совпадает с числом символов.
В обработчике формы сначала загрузите поля через load(), затем вызовите validate(). При неуспехе верните форму с ошибками модели или передайте getErrors() в ответ API. Если присваиваете поля вручную, вызывайте validate() после присваивания.
Способ 2. Вынесите правило в класс Validator
Для проверки одного значения переопределите validateValue(). Верните null при успехе или пару из сообщения и массива параметров при ошибке. Базовый класс сам привяжет ошибку к атрибуту модели. Параметр $value оставьте без объявления типа, как в API Yii 2, и проверьте его внутри метода.
<?php
declare(strict_types=1);
namespace app\validators;
use yii\base\InvalidConfigException;
use yii\helpers\Json;
use yii\validators\Validator;
final class SlugValidator extends Validator
{
public int $maxLength = 80;
public array $reserved = [];
public string $formatMessage = 'Введите до {max} строчных латинских букв, цифр и одиночных дефисов между ними.';
public string $reservedMessage = 'Этот slug зарезервирован.';
public function init(): void
{
parent::init();
if ($this->maxLength < 1) {
throw new InvalidConfigException('maxLength должен быть положительным.');
}
}
protected function validateValue($value): ?array
{
// Якорь \z требует конца строки, включая случай с переводом строки.
if (!is_string($value) || strlen($value) > $this->maxLength
|| preg_match('/\A[a-z0-9]+(?:-[a-z0-9]+)*\z/', $value) !== 1) {
return [$this->formatMessage, ['max' => $this->maxLength]];
}
if (in_array($value, $this->reserved, true)) {
return [$this->reservedMessage, []];
}
return null;
}
public function clientValidateAttribute($model, $attribute, $view): string
{
// Передаём настройки и сообщения в JavaScript через JSON.
$options = Json::htmlEncode([
'maxLength' => $this->maxLength,
'reserved' => array_values($this->reserved),
'formatMessage' => strtr($this->formatMessage, ['{max}' => (string) $this->maxLength]),
'reservedMessage' => $this->reservedMessage,
'skipOnEmpty' => $this->skipOnEmpty,
]);
return <<<JS
(() => {
const options = {$options};
if (value === '' && options.skipOnEmpty) return;
const slugPattern = /^[a-z0-9]+(?:-[a-z0-9]+)*(?![\s\S])/;
if (typeof value !== 'string' || value.length > options.maxLength || !slugPattern.test(value)) {
messages.push(options.formatMessage);
} else if (options.reserved.includes(value)) {
messages.push(options.reservedMessage);
}
})();
JS;
}
}В типовом приложении класс можно сохранить в validators/SlugValidator.php под пространством имён app\validators. В объявлении правила замените имя метода на имя класса. В примере лимит снижен до 60 символов для конкретной формы.
public function rules(): array
{
return [
['slug', 'required'],
// Имя класса Yii использует для создания валидатора.
['slug', \app\validators\SlugValidator::class,
'maxLength' => 60, 'reserved' => ['admin', 'api']],
];
}Класс можно использовать и вне модели через $validator->validate($value, $error). Метод возвращает bool, а второй аргумент получает сообщение при ошибке. Если проверка зависит от других атрибутов модели, переопределите validateAttribute($model, $attribute) и добавляйте ошибки через $this->addError($model, $attribute, $message).
Пустые поля, порядок правил и сценарии
- Пустое значение. При проверке модели Yii по умолчанию пропускает пустое поле для пользовательского валидатора. Поэтому обязательность задаётся отдельным
required. Если ваше правило должно само обработать пустой ввод, укажите'skipOnEmpty' => false. При прямом вызовеValidator::validate()проверяется переданное значение, поэтому пропуск пустых полей из проверки модели здесь не применяется. - Порядок. Объявите
requiredперед проверкой формата. По умолчаниюskipOnErrorпропустит последующее правило, если у поля уже есть ошибка. Если нужно убрать пробелы по краям, поставьте нормализацию перед проверками и учитывайте, что она меняет данные модели. - Сценарии. Через
onограничьте правило нужным сценарием, черезexceptисключите сценарий. Установитеscenarioдоload(), поскольку от него зависит и набор атрибутов, доступных для массового присваивания.
Как работает проверка в ActiveForm
При включённой клиентской валидации yii\widgets\ActiveForm использует JavaScript, который возвращает clientValidateAttribute(). Поле должно быть связано с моделью через $form->field($model, 'slug'). Скрипт получает value и добавляет ошибки в messages. В примере PHP и JavaScript используют собственные способы привязки к концу строки, поэтому оба отклоняют slug с завершающим переводом строки.
Серверный вызов validate() остаётся обязательным для обработки запроса. Для проверки, которая требует данных из базы или доступа к другому сервису, в ActiveForm можно включить enableAjaxValidation и вернуть результат ActiveForm::validate($model) из серверного обработчика после загрузки данных. Если slug должен быть уникальным, закрепите это ограничением в базе: два запроса могут одновременно пройти предварительную проверку. Обработайте конфликт и верните ошибку поля.
Что учесть в проекте на Yii 1.1
В Yii 1.1 метод модели тоже подключают по имени в rules() и регистрируют ошибку через $this->addError($attribute, $message). Переиспользуемый класс наследуют от CValidator и реализуют protected function validateAttribute($object, $attribute). Для CActiveForm предусмотрен clientValidateAttribute($object, $attribute). При переносе правила между ветками сохраните саму проверку, а сигнатуры и настройки формы приведите к API целевой версии.
Чек-лист перед подключением правила
- Проверьте обычный slug
news-2026, зарезервированное имяadmin, двойной дефис, верхний регистр и завершающий перевод строки. - Проверьте строку ровно на пределе длины и на один символ длиннее, а также массив и отсутствующее поле.
- Убедитесь, что для пустого поля в обязательном сценарии появляется сообщение от
required. - Если добавили клиентскую проверку, прогоните те же строковые значения в форме и отправьте запрос с отключённым JavaScript, чтобы проверить серверную обработку.
Частые вопросы
Как передать параметры в свой валидатор Yii 2?
Добавьте именованные параметры в массив правила. Метод модели получит их в аргументе $params, а для отдельного класса Yii передаст настройки через одноимённые свойства.
Почему пользовательский валидатор не вызывается для пустого поля?
При проверке модели по умолчанию действует skipOnEmpty. Добавьте required, если поле обязательно, или установите skipOnEmpty в false, если пустой ввод должен обработать сам валидатор.
Как проверить значение валидатором Yii 2 без модели?
Создайте экземпляр класса, который реализует validateValue(), и вызовите $validator->validate($value, $error). Метод вернёт true или false, а при ошибке запишет сообщение в $error.