Merge pull request #23 from qiansen1386/master

docs/guide-zh-CN/input-validation.md

+输入验证
+================
+
+一般说来，程序猿永远不应该信任从最终用户直接接收到的数据，并且使用它们之前应始终先验证其可靠性。
+
+要给 [model](structure-models.md) 填充其所需的用户输入数据，你可以调用 [[yii\base\Model::validate()]] 方法验证它们。该方法会返回一个布尔值，指明是否通过验证。若没有通过，你能通过 [[yii\base\Model::errors]] 属性获取相应的报错信息。比如，
+
+```php
+$model = new \app\models\ContactForm;
+
+// 用用户输入来填充模型的特性
+$model->attributes = \Yii::$app->request->post('ContactForm');
+
+if ($model->validate()) {
+    // 若所有输入都是有效的
+} else {
+    // 有效性验证失败：$errors 属性就是存储错误信息的数组
+    $errors = $model->errors;
+}
+```
+
+`validate()` 方法，在幕后为执行验证操作，进行了以下步骤：
+
+1. 通过从 [[yii\base\Model::scenarios()]] 方法返回基于当前 [[yii\base\Model::scenario|场景（scenario）]] 的特性属性列表，算出哪些特性应该进行有效性验证。这些属性被称作 *active attributes*（激活特性）。
+2. 通过从 [[yii\base\Model::rules()]] 方法返回基于当前 [[yii\base\Model::scenario|场景（scenario）]] 的验证规则列表，这些规则被称作 *active rules*（激活规则）。
+3. 用每个激活规则去验证每个与之关联的激活特性。若失败，则记录下对应模型特性的错误信息。
+
+
+## 声明规则（Rules） <a name="declaring-rules"></a>
+
+要让 `validate()` 方法起作用，你需要声明与需验证模型特性相关的验证规则。为此，需要重写 [[yii\base\Model::rules()]] 方法。下面的例子展示了如何声明用于验证 `ContactForm` 模型的相关验证规则：
+
+```php
+public function rules()
+{
+    return [
+        // name，email，subject 和 body 特性是 `require`（必填）的
+        [['name', 'email', 'subject', 'body'], 'required'],
+
+        // email 特性必须是一个有效的 email 地址
+        ['email', 'email'],
+    ];
+}
+```
+
+[[yii\base\Model::rules()|rules()]] 方法应返回一个由规则所组成的数组，每一个规则都呈现为以下这类格式的小数组：
+
+```php
+[
+    // required, specifies which attributes should be validated by this rule.
+    // For a single attribute, you can use the attribute name directly
+    // without having it in an array instead of an array
+    ['attribute1', 'attribute2', ...],
+
+    // required, specifies the type of this rule.
+    // It can be a class name, validator alias, or a validation method name
+    'validator',
+
+    // optional, specifies in which scenario(s) this rule should be applied
+    // if not given, it means the rule applies to all scenarios
+    // You may also configure the "except" option if you want to apply the rule
+    // to all scenarios except the listed ones
+    'on' => ['scenario1', 'scenario2', ...],
+
+    // optional, specifies additional configurations for the validator object
+    'property1' => 'value1', 'property2' => 'value2', ...
+]
+```
+
+For each rule you must specify at least which attributes the rule applies to and what is the type of the rule.
+You can specify the rule type in one of the following forms:
+
+* the alias of a core validator, such as `required`, `in`, `date`, etc. Please refer to
+  the [Core Validators](tutorial-core-validators.md) for the complete list of core validators.
+* the name of a validation method in the model class, or an anonymous function. Please refer to the
+  [Inline Validators](#inline-validators) subsection for more details.
+* the name of a validator class. Please refer to the [Standalone Validators](#standalone-validators)
+  subsection for more details.
+
+A rule can be used to validate one or multiple attributes, and an attribute may be validated by one or multiple rules.
+A rule may be applied in certain [scenarios](structure-models.md#scenarios) only by specifying the `on` option.
+If you do not specify an `on` option, it means the rule will be applied to all scenarios.
+
+When the `validate()` method is called, it does the following steps to perform validation:
+
+1. Determine which attributes should be validated by checking the current [[yii\base\Model::scenario|scenario]]
+   against the scenarios declared in [[yii\base\Model::scenarios()]]. These attributes are the active attributes.
+2. Determine which rules should be applied by checking the current [[yii\base\Model::scenario|scenario]]
+   against the rules declared in [[yii\base\Model::rules()]]. These rules are the active rules.
+3. Use each active rule to validate each active attribute which is associated with the rule.
+
+According to the above validation steps, an attribute will be validated if and only if it is
+an active attribute declared in `scenarios()` and is associated with one or multiple active rules
+declared in `rules()`.
+
+
+### 自定义错误信息 <a name="customizing-error-messages"></a>
+
+Most validators have default error messages that will be added to the model being validated when its attributes
+fail the validation. For example, the [[yii\validators\RequiredValidator|required]] validator will add
+a message "Username cannot be blank." to a model when the `username` attribute fails the rule using this validator.
+
+You can customize the error message of a rule by specifying the `message` property when declaring the rule,
+like the following,
+
+```php
+public function rules()
+{
+    return [
+        ['username', 'required', 'message' => 'Please choose a username.'],
+    ];
+}
+```
+
+Some validators may support additional error messages to more precisely describe different causes of
+validation failures. For example, the [[yii\validators\NumberValidator|number]] validator supports
+[[yii\validators\NumberValidator::tooBig|tooBig]] and [[yii\validators\NumberValidator::tooSmall|tooSmall]]
+to describe the validation failure when the value being validated is too big and too small, respectively.
+You may configure these error messages like configuring other properties of validators in a validation rule.
+
+
+### 验证事件 <a name="validation-events"></a>
+
+When [[yii\base\Model::validate()]] is called, it will call two methods that you may override to customize
+the validation process:
+
+* [[yii\base\Model::beforeValidate()]]: the default implementation will trigger a [[yii\base\Model::EVENT_BEFORE_VALIDATE]]
+  event. You may either override this method or respond to this event to do some preprocessing work
+  (e.g. normalizing data inputs) before the validation occurs. The method should return a boolean value indicating
+  whether the validation should proceed or not.
+* [[yii\base\Model::afterValidate()]]: the default implementation will trigger a [[yii\base\Model::EVENT_AFTER_VALIDATE]]
+  event. You may either override this method or respond to this event to do some postprocessing work after
+  the validation is completed.
+
+
+### 条件式验证 <a name="conditional-validation"></a>
+
+To validate attributes only when certain conditions apply, e.g. the validation of one attribute depends
+on the value of another attribute you can use the [[yii\validators\Validator::when|when]] property
+to define such conditions. For example,
+
+```php
+[
+    ['state', 'required', 'when' => function($model) {
+        return $model->country == 'USA';
+    }],
+]
+```
+
+The [[yii\validators\Validator::when|when]] property takes a PHP callable with the following signature:
+
+```php
+/**
+ * @param Model $model the model being validated
+ * @param string $attribute the attribute being validated
+ * @return boolean whether the rule should be applied
+ */
+function ($model, $attribute)
+```
+
+If you also need to support client-side conditional validation, you should configure
+the [[yii\validators\Validator::whenClient|whenClient]] property which takes a string representing a JavaScript
+function whose return value determines whether to apply the rule or not. For example,
+
+```php
+[
+    ['state', 'required', 'when' => function ($model) {
+        return $model->country == 'USA';
+    }, 'whenClient' => "function (attribute, value) {
+        return $('#country').value == 'USA';
+    }"],
+]
+```
+
+
+### 数据过滤 <a name="data-filtering"></a>
+
+User inputs often need to be filtered or preprocessed. For example, you may want to trim the spaces around the
+`username` input. You may use validation rules to achieve this goal.
+
+The following examples shows how to trim the spaces in the inputs and turn empty inputs into nulls by using
+the [trim](tutorial-core-validators.md#trim) and [default](tutorial-core-validators.md#default) core validators:
+
+```php
+[
+    [['username', 'email'], 'trim'],
+    [['username', 'email'], 'default'],
+]
+```
+
+You may also use the more general [filter](tutorial-core-validators.md#filter) validator to perform more complex
+data filtering.
+
+As you can see, these validation rules do not really validate the inputs. Instead, they will process the values
+and save them back to the attributes being validated.
+
+
+### 处理空输入 <a name="handling-empty-inputs"></a>
+
+When input data are submitted from HTML forms, you often need to assign some default values to the inputs
+if they are empty. You can do so by using the [default](tutorial-core-validators.md#default) validator. For example,
+
+```php
+[
+    // set "username" and "email" as null if they are empty
+    [['username', 'email'], 'default'],
+
+    // set "level" to be 1 if it is empty
+    ['level', 'default', 'value' => 1],
+]
+```
+
+By default, an input is considered empty if its value is an empty string, an empty array or a null.
+You may customize the default empty detection logic by configuring the the [[yii\validators\Validator::isEmpty]] property
+with a PHP callable. For example,
+
+```php
+[
+    ['agree', 'required', 'isEmpty' => function ($value) {
+        return empty($value);
+    }],
+]
+```
+
+> Note: Most validators do not handle empty inputs if their [[yii\base\Validator::skipOnEmpty]] property takes
+  the default value true. They will simply be skipped during validation if their associated attributes receive empty
+  inputs. Among the [core validators](tutorial-core-validators.md), only the `captcha`, `default`, `filter`,
+  `required`, and `trim` validators will handle empty inputs.
+
+
+## Ad Hoc Validation <a name="ad-hoc-validation"></a>
+
+Sometimes you need to do *ad hoc validation* for values that are not bound to any model.
+
+If you only need to perform one type of validation (e.g. validating email addresses), you may call
+the [[yii\validators\Validator::validate()|validate()]] method of the desired validator, like the following:
+
+```php
+$email = 'test@example.com';
+$validator = new yii\validators\EmailValidator();
+
+if ($validator->validate($email, $error)) {
+    echo 'Email is valid.';
+} else {
+    echo $error;
+}
+```
+
+> Note: Not all validators support such kind of validation. An example is the [unique](tutorial-core-validators.md#unique)
+  core validator which is designed to work with a model only.
+
+If you need to perform multiple validations against several values, you can use [[yii\base\DynamicModel]]
+which supports declaring both attributes and rules on the fly. Its usage is like the following:
+
+```php
+public function actionSearch($name, $email)
+{
+    $model = DynamicModel::validateData(compact('name', 'email'), [
+        [['name', 'email'], 'string', 'max' => 128],
+        ['email', 'email'],
+    ]);
+
+    if ($model->hasErrors()) {
+        // validation fails
+    } else {
+        // validation succeeds
+    }
+}
+```
+
+The [[yii\base\DynamicModel::validateData()]] method creates an instance of `DynamicModel`, defines the attributes
+using the given data (`name` and `email` in this example), and then calls [[yii\base\Model::validate()]]
+with the given rules.
+
+Alternatively, you may use the following more "classic" syntax to perform ad hoc data validation:
+
+```php
+public function actionSearch($name, $email)
+{
+    $model = new DynamicModel(compact('name', 'email'));
+    $model->addRule(['name', 'email'], 'string', ['max' => 128])
+        ->addRule('email', 'email')
+        ->validate();
+
+    if ($model->hasErrors()) {
+        // validation fails
+    } else {
+        // validation succeeds
+    }
+}
+```
+
+After validation, you can check if the validation succeeds or not by calling the
+[[yii\base\DynamicModel::hasErrors()|hasErrors()]] method, and then get the validation errors from the
+[[yii\base\DynamicModel::errors|errors]] property, like you do with a normal model.
+You may also access the dynamic attributes defined through the model instance, e.g.,
+`$model->name` and `$model->email`.
+
+
+## 创建验证器（Validators） <a name="creating-validators"></a>
+
+Besides using the [core validators](tutorial-core-validators.md) included in the Yii releases, you may also
+create your own validators. You may create inline validators or standalone validators.
+
+
+### 行内验证器（Inline Validators） <a name="inline-validators"></a>
+
+An inline validator is one defined in terms of a model method or an anonymous function. The signature of
+the method/function is:
+
+```php
+/**
+ * @param string $attribute the attribute currently being validated
+ * @param array $params the additional name-value pairs given in the rule
+ */
+function ($attribute, $params)
+```
+
+If an attribute fails the validation, the method/function should call [[yii\base\Model::addError()]] to save
+the error message in the model so that it can be retrieved back later to present to end users.
+
+Below are some examples:
+
+```php
+use yii\base\Model;
+
+class MyForm extends Model
+{
+    public $country;
+    public $token;
+
+    public function rules()
+    {
+        return [
+            // an inline validator defined as the model method validateCountry()
+            ['country', 'validateCountry'],
+
+            // an inline validator defined as an anonymous function
+            ['token', function ($attribute, $params) {
+                if (!ctype_alnum($this->$attribute)) {
+                    $this->addError($attribute, 'The token must contain letters or digits.');
+                }
+            }],
+        ];
+    }
+
+    public function validateCountry($attribute, $params)
+    {
+        if (!in_array($this->$attribute, ['USA', 'Web'])) {
+            $this->addError($attribute, 'The country must be either "USA" or "Web".');
+        }
+    }
+}
+```
+
+> Note: By default, inline validators will not be applied if their associated attributes receive empty inputs
+  or if they have already failed some validation rules. If you want to make sure a rule is always applied,
+  you may configure the [[yii\validators\Validator::skipOnEmpty|skipOnEmpty]] and/or [[yii\validators\Validator::skipOnError|skipOnError]]
+  properties to be false in the rule declarations. For example:
+> ```php
+[
+    ['country', 'validateCountry', 'skipOnEmpty' => false, 'skipOnError' => false],
+]
+```
+
+
+### 独立验证器（Standalone Validators） <a name="standalone-validators"></a>
+
+A standalone validator is a class extending [[yii\validators\Validator]] or its child class. You may implement
+its validation logic by overriding the [[yii\validators\Validator::validateAttribute()]] method. If an attribute
+fails the validation, call [[yii\base\Model::addError()]] to save the error message in the model, like you do
+with [inline validators](#inline-validators). For example,
+
+```php
+namespace app\components;
+
+use yii\validators\Validator;
+
+class CountryValidator extends Validator
+{
+    public function validateAttribute($model, $attribute)
+    {
+        if (!in_array($model->$attribute, ['USA', 'Web'])) {
+            $this->addError($attribute, 'The country must be either "USA" or "Web".');
+        }
+    }
+}
+```
+
+If you want your validator to support validating a value without a model, you should also override
+[[yii\validators\Validator::validate()]]. You may also override [[yii\validators\Validator::validateValue()]]
+instead of `validateAttribute()` and `validate()` because by default the latter two methods are implemented
+by calling `validateValue()`.
+
+
+## 客户端验证器（Client-Side Validation） <a name="client-side-validation"></a>
+
+Client-side validation based on JavaScript is desirable when end users provide inputs via HTML forms, because
+it allows users to find out input errors faster and thus provides better user experience. You may use or implement
+a validator that supports client-side validation *in addition to* server-side validation.
+
+> Info: While client-side validation is desirable, it is not a must. It main purpose is to provider users better
+  experience. Like input data coming from end users, you should never trust client-side validation. For this reason,
+  you should always perform server-side validation by calling [[yii\base\Model::validate()]], like
+  described in the previous subsections.
+
+
+### 使用客户端验证 <a name="using-client-side-validation"></a>
+
+Many [core validators](tutorial-core-validators.md) support client-side validation out-of-box. All you need to do
+is just to use [[yii\widgets\ActiveForm]] to build your HTML forms. For example, `LoginForm` below declares two
+rules: one uses the [required](tutorial-core-validators.md#required) core validator which is supported on both
+client and server sides; the other uses the `validatePassword` inline validator which is only supported on the server
+side.
+
+```php
+namespace app\models;
+
+use yii\base\Model;
+use app\models\User;
+
+class LoginForm extends Model
+{
+    public $username;
+    public $password;
+
+    public function rules()
+    {
+        return [
+            // username and password are both required
+            [['username', 'password'], 'required'],
+
+            // password is validated by validatePassword()
+            ['password', 'validatePassword'],
+        ];
+    }
+
+    public function validatePassword()
+    {
+        $user = User::findByUsername($this->username);
+
+        if (!$user || !$user->validatePassword($this->password)) {
+            $this->addError('password', 'Incorrect username or password.');
+        }
+    }
+}
+```
+
+The HTML form built by the following code contains two input fields `username` and `password`.
+If you submit the form without entering anything, you will find the error messages requiring you
+to enter something appear right away without any communication with the server.
+
+```php
+<?php $form = yii\widgets\ActiveForm::begin(); ?>
+    <?= $form->field($model, 'username') ?>
+    <?= $form->field($model, 'password')->passwordInput() ?>
+    <?= Html::submitButton('Login') ?>
+<?php yii\widgets\ActiveForm::end(); ?>
+```
+
+Behind the scene, [[yii\widgets\ActiveForm]] will read the validation rules declared in the model
+and generate appropriate JavaScript code for validators that support client-side validation. When a user
+changes the value of an input field or submit the form, the client-side validation JavaScript will be triggered.
+
+If you want to turn off client-side validation completely, you may configure the
+[[yii\widgets\ActiveForm::enableClientValidation]] property to be false. You may also turn off client-side
+validation of individual input fields by configuring their [[yii\widgets\ActiveField::enableClientValidation]]
+property to be false.
+
+
+### 实现客户端验证 <a name="implementing-client-side-validation"></a>
+
+To create a validator that supports client-side validation, you should implement the
+[[yii\validators\Validator::clientValidateAttribute()]] method which returns a piece of JavaScript code
+that performs the validation on the client side. Within the JavaScript code, you may use the following
+predefined variables:
+
+- `attribute`: the name of the attribute being validated.
+- `value`: the value being validated.
+- `messages`: an array used to hold the validation error messages for the attribute.
+
+In the following example, we create a `StatusValidator` which validates if an input is a valid status input
+against the existing status data. The validator supports both server side and client side validation.
+
+```php
+namespace app\components;
+
+use yii\validators\Validator;
+use app\models\Status;
+
+class StatusValidator extends Validator
+{
+    public function init()
+    {
+        parent::init();
+        $this->message = 'Invalid status input.';
+    }
+
+    public function validateAttribute($model, $attribute)
+    {
+        $value = $model->$attribute;
+        if (!Status::find()->where(['id' => $value])->exists()) {
+            $model->addError($attribute, $this->message);
+        }
+    }
+
+    public function clientValidateAttribute($model, $attribute, $view)
+    {
+        $statuses = json_encode(Status::find()->select('id')->asArray()->column());
+        $message = json_encode($this->message);
+        return <<<JS
+if (!$.inArray(value, $statuses)) {
+    messages.push($message);
+}
+JS;
+    }
+}
+```
+
+> Tip: The above code is given mainly to demonstrate how to support client-side validation. In practice,
+  you may use the [in](tutorial-core-validators.md#in) core validator to achieve the same goal. You may
+  write the validation rule like the following:
+> ```php
+[
+    ['status', 'in', 'range' => Status::find()->select('id')->asArray()->column()],
+]
+```

docs/guide-zh-CN/tutorial-core-validators.md

+核心验证器（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` 的值相等。该属性支持如下操作符：
+     * `==`：检查两值是否相等。比对为非严格模式。
+     * `===`：检查两值是否全等。比对为严格模式。
+     * `!=`：检查两值是否不等。比对为非严格模式。
+     * `!==`：检查两值是否不全等。比对为严格模式。
+     * `>`：检查待测目标值是否大于给定被测值。
+     * `>=`：检查待测目标值是否大于等于给定被测值。
+     * `<`：检查待测目标值是否小于给定被测值。
+     * `<=`：检查待测目标值是否小于等于给定被测值。
+
+
+## [[yii\validators\DateValidator|date（日期）]] <a name="date"></a>
+
+```php
+[
+    [['from', 'to'], 'date'],
+]
+```
+
+该验证器检查输入值是否为适当格式的 date，time，或者 datetime。另外，它还可以帮你把输入值转换为一个 UNIX 时间戳并保存到 [[yii\validators\DateValidator::timestampAttribute|timestampAttribute]] 属性所指定的特性里。
+
+- `format`：待测的 日期/时间 格式。请参考
+  [date_create_from_format() 相关的 PHP 手册](http://www.php.net/manual/zh/datetime.createfromformat.php)了解设定格式字符串的更多细节。默认值为 `'Y-m-d'`。
+- `timestampAttribute`：用于保存用输入时间/日期转换出来的 UNIX 时间戳的特性。
+
+
+## [[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'));
+    }],
+]
+```
+
+该验证器并不进行数据验证。而是，给为空的待测特性分配默认值。
+
+- `value`：默认值，或一个返回默认值的 PHP Callable 对象（即回调函数）。它们会分配给检测为空的待测特性。PHP 回调方法的样式如下：
+
+```php
+function foo($model, $attribute) {
+    // ... compute $value ...
+    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。
+- `enableIDN`：验证过程是否应该考虑 IDN（internationalized domain names，国际化域名，也称多语种域名，比如中文域名）。默认为 false。要注意但是为使用 IDN 验证功能，请先确保安装并开启 `intl` PHP 扩展，不然会导致抛出异常。
+
+
+## [[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],
+]
+```
+
+该验证器检查输入值是否在表字段中存在。它只对[活动记录](db-active-record.md)模型的特性起作用。它支持对一个或多个字段的验证。
+
+- `targetClass`：用于查找输入值的[活动记录](db-active-record.md)类。若不设置，则会使用当前正在执行验证的模型类。
+- `targetAttribute`：用于检查输入值存在性的 `targetClass` 的模型特性。若不设置，它会使用当前验证的待测特性名。你也可以用数组的形式，同时指定多个用于验证存在性的表字段，数组的键和值都是代表字段的特性名，值表示用于检查存在性的数据源，而键表示待测的特性名。若键和值相同，你可以只指定值。
+- `filter`：用于检查输入值存在性必然会进行数据库查询，而该属性为用于进一步筛选该查询的过滤条件。可以为代表额外查询条件的字符串或数组（关于查询条件的格式，请参考 [[yii\db\Query::where()]]）；或者样式为 `function ($query)` 的匿名函数，`$query` 参数为你希望在该函数内进行修改的 [[yii\db\Query|Query]] 对象。
+- `allowArray`：是否允许输入值为数组。默认为 false。若该属性为 true 且输入值为数组，则数组的每个元素都必须在目标字段中存在。值得注意的是，若用吧 `targetAttribute` 设为多元素数组来验证被测值在多字段中的存在性时，该属性不能设置为 true。
+
+
+## [[yii\validators\FileValidator|file（文件）]] <a name="file"></a>
+
+```php
+[
+    // 检查 "primaryImage" 是否为 PNG, JPG 或 GIF 格式的上传图片。
+    // 文件大小必须小于  1MB
+    ['primaryImage', 'file', 'extensions' => ['png', 'jpg', 'gif'], 'maxSize' => 1024*1024*1024],
+]
+```
+
+该验证器检查输入值是否为一个有效的上传文件。
+
+- `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，代表执行上述检测。
+
+`FileValidator` 通常与 [[yii\web\UploadedFile]] 共同使用。请参考 [文件上传](input-file-upload.md)章节来了解有关文件上传与上传文件的检验的全部内容。
+
+
+## [[yii\validators\FilterValidator|filter（滤镜）]] <a name="filter"></a>
+
+```php
+[
+    // trim 掉 "username" 和 "email" 输入
+    [['username', 'email'], 'filter', 'filter' => 'trim', 'skipOnArray' => true],
+
+    // 标准化 "phone" 输入
+    ['phone', 'filter', 'filter' => function ($value) {
+        // 在此处标准化输入的电话号码
+        return $value;
+    }],
+]
+```
+
+该验证器并不进行数据验证。而是，给输入值应用一个滤镜，并在检验过程之后把它赋值回特性变量。
+
+- `filter`：用于定义滤镜的 PHP 回调函数。可以为全局函数名，匿名函数，或其他。该函数的样式必须是 `function ($value) { return $newValue; }`。该属性不能省略，必须设置。
+- `skipOnArray`：是否在输入值为数组时跳过滤镜。默认为 false。请注意如果滤镜不能处理数组输入，你就应该把该属性设为 true。否则可能会导致 PHP Error 的发生。
+
+> 技巧：如果你只是想要用 trim 处理下输入值，你可以直接用 [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`：用于检查输入值的给定值列表。
+- `strict`：输入值与给定值直接的比较是否为严格模式（也就是类型与值都要相同，即全等）。默认为 false。
+- `not`：是否对验证的结果取反。默认为 false。当该属性被设置为 true，验证器检查输入值是否**不在**给定列表内。
+- `allowArray`：是否接受输入值为数组。当该值为 true 且输入值为数组时，数组内的每一个元素都必须在给定列表内存在，否则返回验证失败。
+
+
+## [[yii\validators\NumberValidator|integer（整数）]] <a name="integer"></a>
+
+```php
+[
+    // 检查 "age" 是否为整数
+    ['age', '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`：检查输入值时是否检查类型。默认为 false。当没有设置 `requiredValue` 属性时，若该属性为 true，验证器会检查输入值是否严格为 null；若该属性设为 false，该验证器会用一个更加宽松的规则检验输入值是否为空。
+
+当设置了 `requiredValue` 属性时，若该属性为 true，输入值与 `requiredValue` 的比对会同时检查数据类型。
+
+> 补充：如何判断待测值是否为空，被写在另外一个话题的[处理空输入](input-validation.md#handling-empty-inputs)章节。
+
+
+## [[yii\validators\SafeValidator|safe（安全）]] <a name="safe"></a>
+
+```php
+[
+    // 标记 "description" 为安全特性
+    ['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`：指定待测输入字符串的长度限制。该属性可以被指定为以下格式之一：
+     * 证书：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`。
+
+
+## [[yii\validators\FilterValidator|trim（译为修剪/裁边）]] <a name="trim"></a>
+
+```php
+[
+    // trim 掉 "username" 和 "email" 两侧的多余空格
+    [['username', 'email'], 'trim'],
+]
+```
+
+该验证器并不进行数据验证。而是，trim 掉输入值两侧的多余空格。注意若该输入值为数组，那它会忽略掉该验证器。
+
+
+## [[yii\validators\UniqueValidator|unique（唯一）]] <a name="unique"></a>
+
+```php
+[
+    // a1 需要在代表 "a1" 特性的表字段中唯一
+    ['a1', 'unique'],
+
+    // a1 需要唯一，但会使用字段 a2 检验 a1 值的唯一性
+    ['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']],
+]
+```
+
+该验证器检查输入值是否在某表字段中唯一。它只对[活动记录](db-active-record.md)模型的特性起作用。它支持对一个或多过字段的验证。
+
+- `targetClass`：用于查找输入值的[活动记录](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。若没有 URI 方案，则给 "website" 特性加 "http://" 前缀
+    ['website', 'url', 'defaultScheme' => 'http'],
+]
+```
+
+该验证器检查输入值是否为有效 URL。
+
+- `validSchemes`：用于指定那些 URI 方案会被视为有效的数组。默认为 `['http', 'https']`，代表 `http` 和 `https` URLs 会被认为有效。
+- `defaultScheme`：若输入值没有对应的方案前缀，会使用的默认 URI 方案前缀。默认为 null，代表不修改输入值本身。
+- `enableIDN`：验证过程是否应该考虑 IDN（internationalized domain names，国际化域名，也称多语种域名，比如中文域名）。默认为 false。要注意但是为使用 IDN 验证功能，请先确保安装并开启 `intl` PHP 扩展，不然会导致抛出异常。