Skip to content

Y
yii2
Commit fc872678 by 东方孤思子（Paris·QianSen）
Options

translating

parent 0f6304ff
Showing with 1013 additions and 0 deletions
docs/guide-zh-CN/input-validation.md 0 → 100644
输入验证
================
一般说来，程序猿永远不应该信任从最终用户直接接收到的数据，并且使用它们之前应始终先验证其可靠性。
要给 [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 0 → 100644
核心验证器（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 needs to exist in the column represented by the "a1" attribute
['a1', 'exist'],
// a1 needs to exist, but its value will use a2 to check for the existence
['a1', 'exist', 'targetAttribute' => 'a2'],
// a1 and a2 need to exist together, and they both will receive error message
[['a1', 'a2'], 'exist', 'targetAttribute' => ['a1', 'a2']],
// a1 and a2 need to exist together, only a1 will receive error message
['a1', 'exist', 'targetAttribute' => ['a1', 'a2']],
// a1 needs to exist by checking the existence of both a2 and a3 (using a1 value)
['a1', 'exist', 'targetAttribute' => ['a2', 'a1' => 'a3']],
// a1 needs to exist. If a1 is an array, then every element of it must exist.
['a1', 'exist', 'allowArray' => true],
]
```
该验证器检查输入值是否在表字段中存在。它只对[活动记录](db-active-record.md)模型的特性起作用。它支持对一个或多过字段的验证。
- `targetClass`：the name of the [Active Record](db-active-record.md) class that should be used
to look for the input value being validated. If not set, the class of the model currently being validated will be used.
- `targetAttribute`：the name of the attribute in `targetClass` that should be used to validate the existence
of the input value. If not set, it will use the name of the attribute currently being validated.
You may use an array to validate the existence of multiple columns at the same time. The array values
are the attributes that will be used to validate the existence, while the array keys are the attributes
whose values are to be validated. If the key and the value are the same, you can just specify the value.
- `filter`：additional filter to be applied to the DB query used to check the existence of the input value.
This can be a string or an array representing the additional query condition (refer to [[yii\db\Query::where()]]
on the format of query condition), or an anonymous function with the signature `function ($query)`, where `$query`
is the [[yii\db\Query|Query]] object that you can modify in the function.
- `allowArray`：whether to allow the input value to be an array. 默认为 false. If this property is true
and the input is an array, then every element of the array must exist in the target column. Note that
this property cannot be set true if you are validating against multiple columns by setting `targetAttribute` as an array.
## [[yii\validators\FileValidator|file]] <a name="file"></a>
```php
[
// checks if "primaryImage" is an uploaded image file in PNG, JPG or GIF format.
// the file size must be less than 1MB
['primaryImage', 'file', 'extensions' => ['png', 'jpg', 'gif'], 'maxSize' => 1024*1024*1024],
]
```
This validator checks if the input is a valid uploaded file.
- `extensions`：a list of file name extensions that are allowed to be uploaded. This can be either
an array or a string consisting of file extension names separated by space or comma (e.g. "gif, jpg").
Extension names are case-insensitive. 默认为 null, meaning all file name
extensions are allowed.
- `mimeTypes`：a list of file MIME types that are allowed to be uploaded. This can be either an array
or a string consisting of file MIME types separated by space or comma (e.g. "image/jpeg, image/png").
Mime type names are case-insensitive. 默认为 null, meaning all MIME types are allowed.
- `minSize`：the minimum number of bytes required for the uploaded file. 默认为 null, meaning no lower limit.
- `maxSize`：the maximum number of bytes allowed for the uploaded file. 默认为 null, meaning no upper limit.
- `maxFiles`：the maximum number of files that the given attribute can hold. 默认为 1, meaning
the input must be a single uploaded file. If it is greater than 1, then the input must be an array
consisting of at most `maxFiles` number of uploaded files.
- `checkExtensionByMimeType`：whether to check the file extension by the file's MIME type. If the extension produced by
MIME type check differs from the uploaded file extension, the file will be considered as invalid. 默认为 true,
meaning perform such check.
`FileValidator` is used together with [[yii\web\UploadedFile]]. Please refer to the [Uploading Files](input-file-upload.md)
section for complete coverage about uploading files and performing validation about the uploaded files.
## [[yii\validators\FilterValidator|filter]] <a name="filter"></a>
```php
[
// trim "username" and "email" inputs
[['username', 'email'], 'filter', 'filter' => 'trim', 'skipOnArray' => true],
// normalize "phone" input
['phone', 'filter', 'filter' => function ($value) {
// normalize phone input here
return $value;
}],
]
```
This validator does not validate data. Instead, it applies a filter on the input value and assigns it
back to the attribute being validated.
- `filter`：a PHP callback that defines a filter. This can be a global function name, an anonymous function, etc.
The function signature must be `function ($value) { return $newValue; }`. This property must be set.
- `skipOnArray`：whether to skip the filter if the input value is an array. 默认为 false.
Note that if the filter cannot handle array input, you should set this property to be true. Otherwise some
PHP error might occur.
> Tip：If you want to trim input values, you may directly use [trim](#trim) validator.
## [[yii\validators\ImageValidator|image]] <a name="image"></a>
```php
[
// checks if "primaryImage" is a valid image with proper size
['primaryImage', 'image', 'extensions' => 'png, jpg',
'minWidth' => 100, 'maxWidth' => 1000,
'minHeight' => 100, 'maxHeight' => 1000,
],
]
```
This validator checks if the input value represents a valid image file. It extends from the [file](#file) validator
and thus inherits all its properties. Besides, it supports the following additional properties specific for image
validation purpose:
- `minWidth`：the minimum width of the image. 默认为 null, meaning no lower limit.
- `maxWidth`：the maximum width of the image. 默认为 null, meaning no upper limit.
- `minHeight`：the minimum height of the image. 默认为 null, meaning no lower limit.
- `maxHeight`：the maximum height of the image. 默认为 null, meaning no upper limit.
## [[yii\validators\RangeValidator|in]] <a name="in"></a>
```php
[
// checks if "level" is 1, 2 or 3
['level', 'in', 'range' => [1, 2, 3]],
]
```
This validator checks if the input value can be found among the given list of values.
- `range`：a list of given values within which the input value should be looked for.
- `strict`：whether the comparison between the input value and the given values should be strict
(both the type and value must be the same). 默认为 false.
- `not`：whether the validation result should be inverted. 默认为 false. When this property is set true,
the validator checks if the input value is NOT among the given list of values.
- `allowArray`：whether to allow the input value to be an array. When this is true and the input value is an array,
every element in the array must be found in the given list of values, or the validation would fail.
## [[yii\validators\NumberValidator|integer]] <a name="integer"></a>
```php
[
// checks if "age" is an integer
['age', 'integer'],
]
```
This validator checks if the input value is an integer.
- `max`：the upper limit (inclusive) of the value. If not set, it means the validator does not check the upper limit.
- `min`：the lower limit (inclusive) of the value. If not set, it means the validator does not check the lower limit.
## [[yii\validators\RegularExpressionValidator|match]] <a name="match"></a>
```php
[
// checks if "username" starts with a letter and contains only word characters
['username', 'match', 'pattern' => '/^[a-z]\w*$/i']
]
```
This validator checks if the input value matches the specified regular expression.
- `pattern`：the regular expression that the input value should match. This property must be set,
or an exception will be thrown.
- `not`：whether to invert the validation result. 默认为 false, meaning the validation succeeds
only if the input value matches the pattern. If this is set true, the validation is considered
successful only if the input value does NOT match the pattern.
## [[yii\validators\NumberValidator|number]] <a name="number"></a>
```php
[
// checks if "salary" is a number
['salary', 'number'],
]
```
This validator checks if the input value is a number. It is equivalent to the [double](#double] validator.
- `max`：the upper limit (inclusive) of the value. If not set, it means the validator does not check the upper limit.
- `min`：the lower limit (inclusive) of the value. If not set, it means the validator does not check the lower limit.
## [[yii\validators\RequiredValidator|required]] <a name="required"></a>
```php
[
// checks if both "username" and "password" are not empty
[['username', 'password'], 'required'],
]
```
This validator checks if the input value is provided and not empty.
- `requiredValue`：the desired value that the input should be. If not set, it means the input should not be empty.
- `strict`：whether to check data types when validating a value. 默认为 false.
When `requiredValue` is not set, if this property is true, the validator will check if the input value is
not strictly null; If this property is false, the validator will use a loose rule to determine a value is empty or not.
When `requiredValue` is set, the comparison between the input and `requiredValue` will also check data types
if this property is true.
> Info：How to determine if a value is empty or not is a separate topic covered
in the [Empty Values](input-validation.md#empty-values) section.
## [[yii\validators\SafeValidator|safe]] <a name="safe"></a>
```php
[
// marks "description" to be a safe attribute
['description', 'safe'],
]
```
This validator does not perform data validation. Instead, it is used to mark an attribute to be
a [safe attribute](structure-models.md#safe-attributes).
## [[yii\validators\StringValidator|string]] <a name="string"></a>
```php
[
// checks if "username" is a string whose length is between 4 and 24
['username', 'string', 'length' => [4, 24]],
]
```
This validator checks if the input value
Validates that the attribute value is of certain length.
- `length`：specifies the length limit of the input string being validated. This can be specified
in one of the following forms:
* an integer：the exact length that the string should be of;
* an array of one element：the minimum length of the input string (e.g. `[8]`). This will overwrite `min`.
* an array of two elements：the minimum and maximum lengths of the input string (e.g. `[8, 128]`)`.
This will overwrite both `min` and `max`.
- `min`：the minimum length of the input string. If not set, it means no minimum length limit.
- `max`：the maximum length of the input string. If not set, it means no maximum length limit.
- `encoding`：the encoding of the input string to be validated. If not set, it will use the application's
[[yii\base\Application::charset|charset]] value which defaults to `UTF-8`.
## [[yii\validators\FilterValidator|trim]] <a name="trim"></a>
```php
[
// trims the white spaces surrounding "username" and "email"
[['username', 'email'], 'trim'],
]
```
This validator does not perform data validation. Instead, it will trim the surrounding white spaces around
the input value. Note that if the input value is an array, it will be ignored by this validator.
## [[yii\validators\UniqueValidator|unique]] <a name="unique"></a>
```php
[
// a1 needs to be unique in the column represented by the "a1" attribute
['a1', 'unique'],
// a1 needs to be unique, but column a2 will be used to check the uniqueness of the a1 value
['a1', 'unique', 'targetAttribute' => 'a2'],
// a1 and a2 need to be unique together, and they both will receive error message
[['a1', 'a2'], 'unique', 'targetAttribute' => ['a1', 'a2']],
// a1 and a2 need to be unique together, only a1 will receive error message
['a1', 'unique', 'targetAttribute' => ['a1', 'a2']],
// a1 needs to be unique by checking the uniqueness of both a2 and a3 (using a1 value)
['a1', 'unique', 'targetAttribute' => ['a2', 'a1' => 'a3']],
]
```
This validator checks if the input value is unique in a table column. It only works
with [Active Record](db-active-record.md) model attributes. It supports validation against
either a single column or multiple columns.
- `targetClass`：the name of the [Active Record](db-active-record.md) class that should be used
to look for the input value being validated. If not set, the class of the model currently being validated will be used.
- `targetAttribute`：the name of the attribute in `targetClass` that should be used to validate the uniqueness
of the input value. If not set, it will use the name of the attribute currently being validated.
You may use an array to validate the uniqueness of multiple columns at the same time. The array values
are the attributes that will be used to validate the uniqueness, while the array keys are the attributes
whose values are to be validated. If the key and the value are the same, you can just specify the value.
- `filter`：additional filter to be applied to the DB query used to check the uniqueness of the input value.
This can be a string or an array representing the additional query condition (refer to [[yii\db\Query::where()]]
on the format of query condition), or an anonymous function with the signature `function ($query)`, where `$query`
is the [[yii\db\Query|Query]] object that you can modify in the function.
## [[yii\validators\UrlValidator|url]] <a name="url"></a>
```php
[
// checks if "website" is a valid URL. Prepend "http://" to the "website" attribute
// if it does not have a URI scheme
['website', 'url', 'defaultScheme' => 'http'],
]
```
This validator checks if the input value is a valid URL.
- `validSchemes`：an array specifying the URI schemes that should be considered valid. 默认为 `['http', 'https']`,
meaning both `http` and `https` URLs are considered to be valid.
- `defaultScheme`：the default URI scheme to be prepended to the input if it does not have the scheme part.
默认为 null, meaning do not modify the input value.
- `enableIDN`：whether the validator should take into account IDN (internationalized domain names).
默认为 false. Note that in order to use IDN validation you have to install and enable the `intl` PHP
extension, otherwise an exception would be thrown.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment