tutorial-core-validators.md 21.7 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76
核心验证器(Core Validators)
===============

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" 是否为布尔类型,即 true 或 false
    ['deleted', 'boolean', 'trueValue' => true, 'falseValue' => false, 'strict' => true],
]
```

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

- `trueValue`: 代表**真**的值。默认为 `'1'`
- `falseValue`:代表**假**的值。默认为 `'0'`
- `strict`:是否要求待测输入必须严格匹配 `trueValue``falseValue`。默认为 `false`


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


## [[yii\captcha\CaptchaValidator|captcha(验证码)]] <a name="captcha"></a>

```php
[
    ['verificationCode', 'captcha'],
]
```

该验证器通常配合 [[yii\captcha\CaptchaAction]] 以及 [[yii\captcha\Captcha]]
使用,以确保某一输入与 [[yii\captcha\Captcha|CAPTCHA]] 小部件所显示的验证代码(verification code)相同。

- `caseSensitive`:对验证代码的比对是否要求大小写敏感。默认为 false。
- `captchaAction`:指向用于渲染 CAPTCHA 图片的 [[yii\captcha\CaptchaAction|CAPTCHA action]] 的 [路由](structure-controllers.md#routes)。默认为 `'site/captcha'`
- `skipOnEmpty`:当输入为空时,是否跳过验证。默认为 false,也就是输入值为必需项。
  

## [[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` 的值相等。该属性支持如下操作符:
     * `==`:检查两值是否相等。比对为非严格模式。
77 78 79
     * `===`:检查两值是否全等。比对为严格模式。
     * `!=`:检查两值是否不等。比对为非严格模式。
     * `!==`:检查两值是否不全等。比对为严格模式。
80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96
     * `>`:检查待测目标值是否大于给定被测值。
     * `>=`:检查待测目标值是否大于等于给定被测值。
     * `<`:检查待测目标值是否小于给定被测值。
     * `<=`:检查待测目标值是否小于等于给定被测值。


## [[yii\validators\DateValidator|date(日期)]] <a name="date"></a>

```php
[
    [['from', 'to'], 'date'],
]
```

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

- `format`:待测的 日期/时间 格式。请参考
97 98
  [date_create_from_format() 相关的 PHP 手册](http://www.php.net/manual/zh/datetime.createfromformat.php)了解设定格式字符串的更多细节。默认值为 `'Y-m-d'`
- `timestampAttribute`:用于保存用输入时间/日期转换出来的 UNIX 时间戳的特性。
99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117


## [[yii\validators\DefaultValueValidator|default(默认值)]] <a name="default"></a>

```php
[
    // 若 "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'));
    }],
]
```

118
该验证器并不进行数据验证。而是,给为空的待测特性分配默认值。
119 120 121 122 123

- `value`:默认值,或一个返回默认值的 PHP Callable 对象(即回调函数)。它们会分配给检测为空的待测特性。PHP 回调方法的样式如下:

```php
function foo($model, $attribute) {
124
    // ... 计算 $value ...
125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159
    return $value;
}
```

> 补充:如何判断待测值是否为空,被写在另外一个话题的[处理空输入](input-validation.md#handling-empty-inputs)章节。


## [[yii\validators\NumberValidator|double(双精度浮点型)]] <a name="double"></a>

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

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

- `max`:上限值(含界点)。若不设置,则验证器不检查上限。
- `min`:下限值(含界点)。若不设置,则验证器不检查下限。


## [[yii\validators\EmailValidator|email(电子邮件)]] <a name="email"></a>

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

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

- `allowName`:检查是否允许带名称的电子邮件地址 (e.g. `张三 <John.san@example.com>`)。 默认为 false。
- `checkDNS`:检查邮箱域名是否存在,且有没有对应的 A 或 MX 记录。不过要知道,有的时候该项检查可能会因为临时性 DNS 故障而失败,哪怕它其实是有效的。默认为 false。
160
- `enableIDN`:验证过程是否应该考虑 IDN(internationalized domain names,国际化域名,也称多语种域名,比如中文域名)。默认为 false。要注意但是为使用 IDN 验证功能,请先确保安装并开启 `intl` PHP 扩展,不然会导致抛出异常。
161 162


163
## [[yii\validators\ExistValidator|exist(存在性)]] <a name="exist"></a>
164 165 166

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

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

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

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

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

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

187
该验证器检查输入值是否在某表字段中存在。它只对[活动记录](db-active-record.md)类型的模型类特性起作用,能支持对一个或多过字段的验证。
188

189 190 191 192 193
- `targetClass`:用于查找输入值的目标 [AR](db-active-record.md) 类。若不设置,则会使用正在进行验证的当前模型类。
- `targetAttribute`:用于检查输入值存在性的 `targetClass` 的模型特性。
    - 若不设置,它会直接使用待测特性名(整个参数数组的首元素)。
    - 除了指定为字符串以外,你也可以用数组的形式,同时指定多个用于验证的表字段,数组的键和值都是代表字段的特性名,值表示 `targetClass` 的待测数据源字段,而键表示当前模型的待测特性名。
    - 若键和值相同,你可以只指定值。(如:`['a2']` 就代表 `['a2'=>'a2']`
194 195
- `filter`:用于检查输入值存在性必然会进行数据库查询,而该属性为用于进一步筛选该查询的过滤条件。可以为代表额外查询条件的字符串或数组(关于查询条件的格式,请参考 [[yii\db\Query::where()]]);或者样式为 `function ($query)` 的匿名函数,`$query` 参数为你希望在该函数内进行修改的 [[yii\db\Query|Query]] 对象。
- `allowArray`:是否允许输入值为数组。默认为 false。若该属性为 true 且输入值为数组,则数组的每个元素都必须在目标字段中存在。值得注意的是,若用吧 `targetAttribute` 设为多元素数组来验证被测值在多字段中的存在性时,该属性不能设置为 true。
196

197 198 199 200 201
> 译者注:[exist](#exist) 和 [unique](#unique) 验证器的机理和参数都相似,有点像一体两面的阴和阳。
- 他们的区别是 exist 要求 `targetAttribute` 键所代表的的属性在其值所代表字段中找得到;而 unique 正相反,要求键所代表的的属性不能在其值所代表字段中被找到。
- 从另一个角度来理解:他们都会在验证的过程中执行数据库查询,查询的条件即为where $v=$k (假设 `targetAttribute` 的其中一对键值对为 `$k => $v`)。unique 要求查询的结果数 `$count==0`,而 exist 则要求查询的结果数 `$count>0`
- 最后别忘了,unique 验证器不存在 `allowArray` 属性哦。

202

203
## [[yii\validators\FileValidator|file(文件)]] <a name="file"></a>
204 205 206

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

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

215 216 217 218 219 220 221 222
- `extensions`:可接受上传的文件扩展名列表。它可以是数组,也可以是用空格或逗号分隔各个扩展名的字符串 (e.g. "gif, jpg")。
  扩展名大小写不敏感。默认为 null,意味着所有扩展名都被接受。
- `mimeTypes`:可接受上传的 MIME 类型列表。它可以是数组,也可以是用空格或逗号分隔各个 MIME 的字符串 (e.g. "image/jpeg, image/png")。
  Mime 类型名是大小写不敏感的。默认为 null,意味着所有 MIME 类型都被接受。
- `minSize`:上传文件所需最少多少 Byte 的大小。默认为 null,代表没有下限。
- `maxSize`:上传文件所需最多多少 Byte 的大小。默认为 null,代表没有上限。
- `maxFiles`:给定特性最多能承载多少个文件。默认为 1,代表只允许单文件上传。若值大于一,那么输入值必须为包含最多 `maxFiles` 个上传文件元素的数组。
- `checkExtensionByMimeType`:是否通过文件的 MIME 类型来判断其文件扩展。若由 MIME 判定的文件扩展与给定文件的扩展不一样,则文件会被认为无效。默认为 true,代表执行上述检测。
223

224
`FileValidator` 通常与 [[yii\web\UploadedFile]] 共同使用。请参考 [文件上传](input-file-upload.md)章节来了解有关文件上传与上传文件的检验的全部内容。
225 226


227
## [[yii\validators\FilterValidator|filter(滤镜)]] <a name="filter"></a>
228 229 230

```php
[
231
    // trim 掉 "username" 和 "email" 输入
232 233
    [['username', 'email'], 'filter', 'filter' => 'trim', 'skipOnArray' => true],

234
    // 标准化 "phone" 输入
235
    ['phone', 'filter', 'filter' => function ($value) {
236
        // 在此处标准化输入的电话号码
237 238 239 240 241
        return $value;
    }],
]
```

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

244 245
- `filter`:用于定义滤镜的 PHP 回调函数。可以为全局函数名,匿名函数,或其他。该函数的样式必须是 `function ($value) { return $newValue; }`。该属性不能省略,必须设置。
- `skipOnArray`:是否在输入值为数组时跳过滤镜。默认为 false。请注意如果滤镜不能处理数组输入,你就应该把该属性设为 true。否则可能会导致 PHP Error 的发生。
246

247
> 技巧:如果你只是想要用 trim 处理下输入值,你可以直接用 [trim](#trim) 验证器的。
248 249


250
## [[yii\validators\ImageValidator|image(图片)]] <a name="image"></a>
251 252 253

```php
[
254
    // 检查 "primaryImage" 是否为适当尺寸的有效图片
255 256 257 258 259 260 261
    ['primaryImage', 'image', 'extensions' => 'png, jpg',
        'minWidth' => 100, 'maxWidth' => 1000,
        'minHeight' => 100, 'maxHeight' => 1000,
    ],
]
```

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

264 265 266 267
- `minWidth`:图片的最小宽度。默认为 null,代表无下限。
- `maxWidth`:图片的最大宽度。默认为 null,代表无上限。
- `minHeight`:图片的最小高度。 默认为 null,代表无下限。
- `maxHeight`:图片的最大高度。默认为 null,代表无上限。
268 269


270
## [[yii\validators\RangeValidator|in(范围)]] <a name="in"></a>
271 272 273

```php
[
274
    // 检查 "level" 是否为 1、2 或 3 中的一个
275 276 277 278
    ['level', 'in', 'range' => [1, 2, 3]],
]
```

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

281 282 283 284
- `range`:用于检查输入值的给定值列表。
- `strict`:输入值与给定值直接的比较是否为严格模式(也就是类型与值都要相同,即全等)。默认为 false。
- `not`:是否对验证的结果取反。默认为 false。当该属性被设置为 true,验证器检查输入值是否**不在**给定列表内。
- `allowArray`:是否接受输入值为数组。当该值为 true 且输入值为数组时,数组内的每一个元素都必须在给定列表内存在,否则返回验证失败。
285 286


287
## [[yii\validators\NumberValidator|integer(整数)]] <a name="integer"></a>
288 289 290

```php
[
291
    // 检查 "age" 是否为整数
292 293 294 295
    ['age', 'integer'],
]
```

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

298 299
- `max`:上限值(含界点)。若不设置,则验证器不检查上限。
- `min`:下限值(含界点)。若不设置,则验证器不检查下限。
300 301


302
## [[yii\validators\RegularExpressionValidator|match(正则表达式)]] <a name="match"></a>
303 304 305

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

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

313 314
- `pattern`:用于检测输入值的正则表达式。该属性是必须的,若不设置则会抛出异常。
- `not`:是否对验证的结果取反。默认为 false,代表输入值匹配正则表达式时验证成功。如果设为 true,则输入值不匹配正则时返回匹配成功。
315 316


317
## [[yii\validators\NumberValidator|number(数字)]] <a name="number"></a>
318 319 320

```php
[
321
    // 检查 "salary" 是否为数字
322 323 324 325
    ['salary', 'number'],
]
```

326
该验证器检查输入值是否为数字。他等效于 [double](#double) 验证器。
327

328 329
- `max`:上限值(含界点)。若不设置,则验证器不检查上限。
- `min`:下限值(含界点)。若不设置,则验证器不检查下限。
330 331


332
## [[yii\validators\RequiredValidator|required(必填)]] <a name="required"></a>
333 334 335

```php
[
336
    // 检查 "username" 与 "password" 是否为空
337 338 339 340
    [['username', 'password'], 'required'],
]
```

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

343 344
- `requiredValue`:所期望的输入值。若没设置,意味着输入不能为空。
- `strict`:检查输入值时是否检查类型。默认为 false。当没有设置 `requiredValue` 属性时,若该属性为 true,验证器会检查输入值是否严格为 null;若该属性设为 false,该验证器会用一个更加宽松的规则检验输入值是否为空。
345

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

> 补充:如何判断待测值是否为空,被写在另外一个话题的[处理空输入](input-validation.md#handling-empty-inputs)章节。
349 350


351
## [[yii\validators\SafeValidator|safe(安全)]] <a name="safe"></a>
352 353 354

```php
[
355
    // 标记 "description" 为安全特性
356 357 358 359
    ['description', 'safe'],
]
```

360
该验证器并不进行数据验证。而是把一个特性标记为[安全特性](structure-models.md#safe-attributes)
361 362


363
## [[yii\validators\StringValidator|string(字符串)]] <a name="string"></a>
364 365 366

```php
[
367
    // 检查 "username" 是否为长度 4 到 24 之间的字符串
368 369 370 371
    ['username', 'string', 'length' => [4, 24]],
]
```

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

374 375 376 377 378 379 380 381
- `length`:指定待测输入字符串的长度限制。该属性可以被指定为以下格式之一:
     * 证书:the exact length that the string should be of;
     * 单元素数组:代表输入字符串的最小长度 (e.g. `[8]`)。这会重写 `min` 属性。
     * 包含两个元素的数组:代表输入字符串的最小和最大长度(e.g. `[8, 128]`)。
     这会同时重写 `min``max` 属性。
- `min`:输入字符串的最小长度。若不设置,则代表不设下限。
- `max`:输入字符串的最大长度。若不设置,则代表不设上限。
- `encoding`:待测字符串的编码方式。若不设置,则使用应用自身的 [[yii\base\Application::charset|charset]] 属性值,该值默认为 `UTF-8`
382 383


384
## [[yii\validators\FilterValidator|trim(译为修剪/裁边)]] <a name="trim"></a>
385 386 387

```php
[
388
    // trim 掉 "username" 和 "email" 两侧的多余空格
389 390 391 392
    [['username', 'email'], 'trim'],
]
```

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


396
## [[yii\validators\UniqueValidator|unique(唯一性)]] <a name="unique"></a>
397 398 399

```php
[
400
    // a1 需要在 "a1" 特性所代表的字段内唯一
401 402
    ['a1', 'unique'],

403
    // a1 需要唯一,但检验的是 a1 的值在字段 a2 中的唯一性
404 405
    ['a1', 'unique', 'targetAttribute' => 'a2'],

406
    // a1 和 a2 的组合需要唯一,且它们都能收到错误提示
407 408
    [['a1', 'a2'], 'unique', 'targetAttribute' => ['a1', 'a2']],

409
    // a1 和 a2 的组合需要唯一,只有 a1 能接收错误提示
410 411
    ['a1', 'unique', 'targetAttribute' => ['a1', 'a2']],

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

417
该验证器检查输入值是否在某表字段中唯一。它只对[活动记录](db-active-record.md)类型的模型类特性起作用,能支持对一个或多过字段的验证。
418

419 420 421 422 423
- `targetClass`:用于查找输入值的目标 [AR](db-active-record.md) 类。若不设置,则会使用正在进行验证的当前模型类。
- `targetAttribute`:用于检查输入值唯一性的 `targetClass` 的模型特性。
    - 若不设置,它会直接使用待测特性名(整个参数数组的首元素)。
    - 除了指定为字符串以外,你也可以用数组的形式,同时指定多个用于验证的表字段,数组的键和值都是代表字段的特性名,值表示 `targetClass` 的待测数据源字段,而键表示当前模型的待测特性名。
    - 若键和值相同,你可以只指定值。(如:`['a2']` 就代表 `['a2'=>'a2']`
424
- `filter`:用于检查输入值唯一性必然会进行数据库查询,而该属性为用于进一步筛选该查询的过滤条件。可以为代表额外查询条件的字符串或数组(关于查询条件的格式,请参考 [[yii\db\Query::where()]]);或者样式为 `function ($query)` 的匿名函数,`$query` 参数为你希望在该函数内进行修改的 [[yii\db\Query|Query]] 对象。
425

426 427 428 429 430
> 译者注:[exist](#exist) 和 [unique](#unique) 验证器的机理和参数都相似,有点像一体两面的阴和阳。
- 他们的区别是 exist 要求 `targetAttribute` 键所代表的的属性在其值所代表字段中找得到;而 unique 正相反,要求键所代表的的属性不能在其值所代表字段中被找到。
- 从另一个角度来理解:他们都会在验证的过程中执行数据库查询,查询的条件即为where $v=$k (假设 `targetAttribute` 的其中一对键值对为 `$k => $v`)。unique 要求查询的结果数 `$count==0`,而 exist 则要求查询的结果数 `$count>0`
- 最后别忘了,unique 验证器不存在 `allowArray` 属性哦。

431

432
## [[yii\validators\UrlValidator|url(网址)]] <a name="url"></a>
433 434 435

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

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

443 444
- `validSchemes`:用于指定那些 URI 方案会被视为有效的数组。默认为 `['http', 'https']`,代表 `http``https` URLs 会被认为有效。
- `defaultScheme`:若输入值没有对应的方案前缀,会使用的默认 URI 方案前缀。默认为 null,代表不修改输入值本身。
445
- `enableIDN`:验证过程是否应该考虑 IDN(internationalized domain names,国际化域名,也称多语种域名,比如中文域名)。默认为 false。要注意但是为使用 IDN 验证功能,请先确保安装并开启 `intl` PHP 扩展,不然会导致抛出异常。