核心验证器（Core Validators）

核心验证器（Core Validators）

Yii 提供一系列常用的核心验证器，主要存在于 yii\validators 命名空间之下。为了避免使用冗长的类名，你可以直接用昵称来指定相应的核心验证器。比如你可以用 required 昵称代指 yii\validators\RequiredValidator 类：

public function rules()
{
    return [
        [['email', 'password'], 'required'],
    ];
}

yii\validators\Validator::builtInValidators 属性声明了所有被支持的验证器昵称。

下面，我们将详细介绍每一款验证器的主要用法和属性。

yii\validators\BooleanValidator

[
    // 检查 "selected" 是否为 0 或 1，无视数据类型
    ['selected', 'boolean'],

    // 检查 "deleted" 是否为布尔类型，即 true 或 false
    ['deleted', 'boolean', 'trueValue' => true, 'falseValue' => false, 'strict' => true],
]

该验证器检查输入值是否为一个布尔值。

• trueValue： 代表真的值。默认为 '1'。

注意：因为通过 HTML 表单传递的输入数据都是字符串类型，所以一般情况下你都需要保持 yii\validators\BooleanValidator::strict 属性为假。

yii\captcha\CaptchaValidator

[
    ['verificationCode', 'captcha'],
]

该验证器通常配合 yii\captcha\CaptchaAction 以及 yii\captcha\Captcha 使用，以确保某一输入与 yii\captcha\Captcha 小部件所显示的验证代码（verification code）相同。

• caseSensitive：对验证代码的比对是否要求大小写敏感。默认为 false。

[
    // 检查 "password" 特性的值是否与 "password_repeat" 的值相同
    ['password', 'compare'],

    // 检查年龄是否大于等于 30
    ['age', 'compare', 'compareValue' => 30, 'operator' => '>='],
]

该验证器比较两个特定输入值之间的关系是否与 operator 属性所指定的相同。

• compareAttribute：用于与原特性相比较的特性名称。当该验证器被用于验证某目标特性时，该属性会默认为目标属性加后缀_repeat。举例来说，若目标特性为 password，则该属性默认为 password_repeat。

​

yii\validators\DateValidator

[
    [['from', 'to'], 'date'],
]

该验证器检查输入值是否为适当格式的 date，time，或者 datetime。另外，它还可以帮你把输入值转换为一个 UNIX 时间戳并保存到 yii\validators\DateValidator::timestampAttribute 属性所指定的特性里。

• format：待测的 日期/时间 格式。请参考 date_create_from_format() 相关的 PHP 手册了解设定格式字符串的更多细节。默认值为'Y-m-d'。

yii\validators\DefaultValueValidator

[
    // 若 "age" 为空，则将其设为 null
    ['age', 'default', 'value' => null],

    // 若 "country" 为空，则将其设为 "USA"
    ['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 Callable 对象（即回调函数）。它们会分配给检测为空的待测特性。PHP 回调方法的样式如下：

function foo($model, $attribute) {
    // ... 计算 $value ...
    return $value;
}

补充：如何判断待测值是否为空，被写在另外一个话题的处理空输入章节。

yii\validators\NumberValidator

[
    // 检查 "salary" 是否为浮点数
    ['salary', 'double'],
]

该验证器检查输入值是否为双精度浮点数。他等效于 number 验证器。

• max：上限值（含界点）。若不设置，则验证器不检查上限。

[
    // 检查 "email" 是否为有效的邮箱地址
    ['email', 'email'],
]

该验证器检查输入值是否为有效的邮箱地址。

• allowName：检查是否允许带名称的电子邮件地址 (e.g. 张三 <John.san@example.com>)。 默认为 false。

yii\validators\ExistValidator

[
    // a1 需要在 "a1" 特性所代表的字段内存在
    ['a1', 'exist'],

    // a1 必需存在，但检验的是 a1 的值在字段 a2 中的存在性
    ['a1', 'exist', 'targetAttribute' => 'a2'],

    // a1 和 a2 的值都需要存在，且它们都能收到错误提示
    [['a1', 'a2'], 'exist', 'targetAttribute' => ['a1', 'a2']],

    // a1 和 a2 的值都需要存在，只有 a1 能接收到错误信息
    ['a1', 'exist', 'targetAttribute' => ['a1', 'a2']],

    // 通过同时在 a2 和 a3 字段中检查 a2 和 a1 的值来确定 a1 的存在性
    ['a1', 'exist', 'targetAttribute' => ['a2', 'a1' => 'a3']],

    // a1 必需存在，若 a1 为数组，则其每个子元素都必须存在。
    ['a1', 'exist', 'allowArray' => true],
]

该验证器检查输入值是否在某表字段中存在。它只对活动记录类型的模型类特性起作用，能支持对一个或多过字段的验证。

• targetClass：用于查找输入值的目标 AR 类。若不设置，则会使用正在进行验证的当前模型类。

​

• filter：用于检查输入值存在性必然会进行数据库查询，而该属性为用于进一步筛选该查询的过滤条件。可以为代表额外查询条件的字符串或数组（关于查询条件的格式，请参考 yii\db\Query::where()）；或者样式为 function ($query) 的匿名函数，$query参数为你希望在该函数内进行修改的 yii\db\Query 对象。

译注：exist 和 unique 验证器的机理和参数都相似，有点像一体两面的阴和阳。

• 他们的区别是 exist 要求 targetAttribute 键所代表的的属性在其值所代表字段中找得到；而 unique 正相反，要求键所代表的的属性不能在其值所代表字段中被找到。

​

yii\validators\FileValidator

[
    // 检查 "primaryImage" 是否为 PNG, JPG 或 GIF 格式的上传图片。
    // 文件大小必须小于  1MB
    ['primaryImage', 'file', 'extensions' => ['png', 'jpg', 'gif'], 'maxSize' => 1024*1024*1024],
]

该验证器检查输入值是否为一个有效的上传文件。

• extensions：可接受上传的文件扩展名列表。它可以是数组，也可以是用空格或逗号分隔各个扩展名的字符串 (e.g. "gif, jpg")。 扩展名大小写不敏感。默认为 null，意味着所有扩展名都被接受。

FileValidator 通常与 yii\web\UploadedFile 共同使用。请参考 文件上传章节来了解有关文件上传与上传文件的检验的全部内容。

yii\validators\FilterValidator

[
    // trim 掉 "username" 和 "email" 输入
    [['username', 'email'], 'filter', 'filter' => 'trim', 'skipOnArray' => true],

    // 标准化 "phone" 输入
    ['phone', 'filter', 'filter' => function ($value) {
        // 在此处标准化输入的电话号码
        return $value;
    }],
]

该验证器并不进行数据验证。而是，给输入值应用一个滤镜，并在检验过程之后把它赋值回特性变量。

• filter：用于定义滤镜的 PHP 回调函数。可以为全局函数名，匿名函数，或其他。该函数的样式必须是 function ($value) { return $newValue; }。该属性不能省略，必须设置。

技巧：如果你只是想要用 trim 处理下输入值，你可以直接用 trim 验证器的。

yii\validators\ImageValidator

[
    // 检查 "primaryImage" 是否为适当尺寸的有效图片
    ['primaryImage', 'image', 'extensions' => 'png, jpg',
        'minWidth' => 100, 'maxWidth' => 1000,
        'minHeight' => 100, 'maxHeight' => 1000,
    ],
]

该验证器检查输入值是否为代表有效的图片文件。它继承自 file 验证器，并因此继承有其全部属性。除此之外，它还支持以下为图片检验而设的额外属性：

• minWidth：图片的最小宽度。默认为 null，代表无下限。

[
    // 检查 "level" 是否为 1、2 或 3 中的一个
    ['level', 'in', 'range' => [1, 2, 3]],
]

该验证器检查输入值是否存在于给定列表的范围之中。

• range：用于检查输入值的给定值列表。

[
    // 检查 "age" 是否为整数
    ['age', 'integer'],
]

该验证器检查输入值是否为整形。

• max：上限值（含界点）。若不设置，则验证器不检查上限。

[
    // 检查 "username" 是否由字母开头，且只包含单词字符
    ['username', 'match', 'pattern' => '/^[a-z]\w*$/i']
]

该验证器检查输入值是否匹配指定正则表达式。

• pattern：用于检测输入值的正则表达式。该属性是必须的，若不设置则会抛出异常。

[
    // 检查 "salary" 是否为数字
    ['salary', 'number'],
]

该验证器检查输入值是否为数字。他等效于 double 验证器。

• max：上限值（含界点）。若不设置，则验证器不检查上限。

[
    // 检查 "username" 与 "password" 是否为空
    [['username', 'password'], 'required'],
]

该验证器检查输入值是否为空，还是已经提供了。

• requiredValue：所期望的输入值。若没设置，意味着输入不能为空。

当设置了 requiredValue 属性时，若该属性为 true，输入值与 requiredValue 的比对会同时检查数据类型。

补充：如何判断待测值是否为空，被写在另外一个话题的处理空输入章节。

yii\validators\SafeValidator

[
    // 标记 "description" 为安全特性
    ['description', 'safe'],
]

该验证器并不进行数据验证。而是把一个特性标记为安全特性。

yii\validators\StringValidator

[
    // 检查 "username" 是否为长度 4 到 24 之间的字符串
    ['username', 'string', 'length' => [4, 24]],
]

该验证器检查输入值是否为特定长度的字符串。并检查特性的值是否为某个特定长度。

• length：指定待测输入字符串的长度限制。该属性可以被指定为以下格式之一：

​

• min：输入字符串的最小长度。若不设置，则代表不设下限。

[
    // trim 掉 "username" 和 "email" 两侧的多余空格
    [['username', 'email'], 'trim'],
]

该验证器并不进行数据验证。而是，trim 掉输入值两侧的多余空格。注意若该输入值为数组，那它会忽略掉该验证器。

yii\validators\UniqueValidator

[
    // a1 需要在 "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']],

    // 通过同时在 a2 和 a3 字段中检查 a2 和 a3 的值来确定 a1 的唯一性
    ['a1', 'unique', 'targetAttribute' => ['a2', 'a1' => 'a3']],
]

该验证器检查输入值是否在某表字段中唯一。它只对活动记录类型的模型类特性起作用，能支持对一个或多过字段的验证。

• targetClass：用于查找输入值的目标 AR 类。若不设置，则会使用正在进行验证的当前模型类。

​

• filter：用于检查输入值唯一性必然会进行数据库查询，而该属性为用于进一步筛选该查询的过滤条件。可以为代表额外查询条件的字符串或数组（关于查询条件的格式，请参考 yii\db\Query::where()）；或者样式为 function ($query) 的匿名函数，$query参数为你希望在该函数内进行修改的 yii\db\Query 对象。

译注：exist 和 unique 验证器的机理和参数都相似，有点像一体两面的阴和阳。

• 他们的区别是 exist 要求 targetAttribute 键所代表的的属性在其值所代表字段中找得到；而 unique 正相反，要求键所代表的的属性不能在其值所代表字段中被找到。

​

yii\validators\UrlValidator

[
    // 检查 "website" 是否为有效的 URL。若没有 URI 方案，则给 "website" 特性加 "http://" 前缀
    ['website', 'url', 'defaultScheme' => 'http'],
]

该验证器检查输入值是否为有效 URL。

• validSchemes：用于指定那些 URI 方案会被视为有效的数组。默认为 ['http', 'https']，代表 http 和 https URLs 会被认为有效。