Class yii\validators\Validator
Validator 是所有校验器的基类。
子类需要重写 validateValue() 或者/和 validateAttribute() 方法, 来提供实际的数据校验逻辑。 子类也可以重写 clientValidateAttribute() 方法来提供客户端校验功能支持。
Validator 声明了一系列内建校验器 built-in validators 可以使用短名称来引用。 它们列表如下:
boolean
: yii\validators\BooleanValidatorcaptcha
: yii\captcha\CaptchaValidatorcompare
: yii\validators\CompareValidatordate
: yii\validators\DateValidatordatetime
: yii\validators\DateValidatortime
: yii\validators\DateValidatordefault
: yii\validators\DefaultValueValidatordouble
: yii\validators\NumberValidatoreach
: yii\validators\EachValidatoremail
: yii\validators\EmailValidatorexist
: yii\validators\ExistValidatorfile
: yii\validators\FileValidatorfilter
: yii\validators\FilterValidatorimage
: yii\validators\ImageValidatorin
: yii\validators\RangeValidatorinteger
: yii\validators\NumberValidatormatch
: yii\validators\RegularExpressionValidatorrequired
: yii\validators\RequiredValidatorsafe
: yii\validators\SafeValidatorstring
: yii\validators\StringValidatortrim
: yii\validators\FilterValidatorunique
: yii\validators\UniqueValidatorurl
: yii\validators\UrlValidatorip
: yii\validators\IpValidator
关于校验器的更多细节和使用详情,参阅 guide article on validators。
公共属性
属性 | 类型 | 描述 | 被定义在 |
---|---|---|---|
$attributeNames | array | 属性名称列表. | yii\validators\Validator |
$attributes | array|string | 将要被这个校验器校验的属性名,或者列表。如果多属性,请通过一个数组设置它们。 对于单属性,你可以使用一个字符串,也可以使用一个数组指定。 | yii\validators\Validator |
$behaviors | yii\base\Behavior[] | List of behaviors attached to this component | yii\base\Component |
$builtInValidators | array | List of built-in validators (name => class or configuration) | yii\validators\Validator |
$enableClientValidation | boolean | 是否启用这个校验器的客户端校验。 实际的校验过程是通过 clientValidateAttribute() 返回的 JS 代码来执行。 如果这个方法返回 null, 即使这个属性值为 true ,也不会执行任何客户端校验。 | yii\validators\Validator |
$except | array|string | 校验器不应该应用的情景。 对于多情景,请以一个数组的形式指定它们。对于单情景,你可以使用一个字符串或者一个数组。 | yii\validators\Validator |
$isEmpty | callable | 用于替换默认的 isEmpty() 空值校验方法,
如果没有设置,将会使用 isEmpty() 做空值校验。
这个函数的声明应该为 function ($value) ,
它的返回值为一个代表这个值是否为空的布尔值。 |
yii\validators\Validator |
$message | string | 用户定义的错误消息。
它可以使用如下的占位符,并将会相应地被校验器替换:
- {attribute} : 被校验的属性标签
- {value} : 被校验的属性值
注意:有一些校验器会引入其他的属性用于指定的校验条件未满足时的错误消息。
关于这些属性的具体详情,请参考具体的类 API 文档。
通常,
这些属性代表最重要的校验规则未满足时的所触发的主要错误消息。 |
yii\validators\Validator |
$on | array|string | 校验器被应用的情景。 对于多情景,请以一个数组的形式指定它们。对于单情景,你可以使用一个字符串或者一个数组。 | yii\validators\Validator |
$skipOnEmpty | boolean | 当被校验的属性值为 null 或者空字符串时, 是否该跳过这个校验规则。 | yii\validators\Validator |
$skipOnError | boolean | 当被校验的属性根据之前的校验规则已经有一些校验错误时,这个校验规则是否应该被跳过。 默认为 true。 | yii\validators\Validator |
$validationAttributes | yii\validators\Validator | ||
$when | callable | 一个PHP函数调用,它的返回值将会决定这个校验器是否被应用。
这个函数的声明应该为 function ($model, $attribute) ,其中 $model 和 $attribute 代表被校验的模型和属性。
这个函数应该返回一个布尔值。
这个属性主要用于支持服务端条件校验。
如果这个属性没有被设置,这个校验器将会总是在服务端执行校验。
以下是一个示例,只有当前选择的国家为 USA 时,才会在服务端执行此校验器:
` php
function ($model) {
return $model->country == Country::USA;
}
` |
yii\validators\Validator |
$whenClient | string | 这是一个 JS 函数,它的返回值将会决定校验器是否在客户端执行。
这个函数的声明应该为 function (attribute, value) ,
其中 attribute 代表被要被校验的属性对象(参考: clientValidateAttribute()),
value 是属性当前值。
这个属性主要用于支持客户端条件校验。
如果这个属性没有被设置,这个校验器将会总是在客户端执行校验。
以下是一个示例,只有当前选择的国家为 USA 时,才会在客户端执行此校验器:
` javascript
function (attribute, value) {
return $('#country'). |
yii\validators\Validator |
公共方法
方法 | 描述 | 被定义在 |
---|---|---|
__call() | Calls the named method which is not a class method. | yii\base\Component |
__clone() | This method is called after the object is created by cloning an existing one. | yii\base\Component |
__construct() | Constructor. | yii\base\BaseObject |
__get() | Returns the value of a component property. | yii\base\Component |
__isset() | Checks if a property is set, i.e. defined and not null. | yii\base\Component |
__set() | Sets the value of a component property. | yii\base\Component |
__unset() | Sets a component property to be null. | yii\base\Component |
addError() | 添加指定属性的错误到模型对象中。 这是一个帮助方法用于执行消息的选择和国际化。 | yii\validators\Validator |
attachBehavior() | Attaches a behavior to this component. | yii\base\Component |
attachBehaviors() | Attaches a list of behaviors to the component. | yii\base\Component |
behaviors() | Returns a list of behaviors that this component should behave as. | yii\base\Component |
canGetProperty() | Returns a value indicating whether a property can be read. | yii\base\Component |
canSetProperty() | Returns a value indicating whether a property can be set. | yii\base\Component |
className() | Returns the fully qualified name of this class. | yii\base\BaseObject |
clientValidateAttribute() | 返回可用于客户端校验的 JS 代码。 | yii\validators\Validator |
createValidator() | 创建校验器对象。 | yii\validators\Validator |
detachBehavior() | Detaches a behavior from the component. | yii\base\Component |
detachBehaviors() | Detaches all behaviors from the component. | yii\base\Component |
ensureBehaviors() | Makes sure that the behaviors declared in behaviors() are attached to this component. | yii\base\Component |
getAttributeNames() | 返回去除开头 ! 的属性名称。 |
yii\validators\Validator |
getBehavior() | Returns the named behavior object. | yii\base\Component |
getBehaviors() | Returns all behaviors attached to this component. | yii\base\Component |
getClientOptions() | 返回客户端校验参数。 这个方法通常在 clientValidateAttribute() 中调用。 你可以改写这个方法用于修改传给客户端校验的参数。 | yii\validators\Validator |
getValidationAttributes() | yii\validators\Validator | |
hasEventHandlers() | Returns a value indicating whether there is any handler attached to the named event. | yii\base\Component |
hasMethod() | Returns a value indicating whether a method is defined. | yii\base\Component |
hasProperty() | Returns a value indicating whether a property is defined for this component. | yii\base\Component |
init() | Initializes the object. | yii\validators\Validator |
isActive() | 返回一个值代表当前校验器在当前情景和属性下是否是激活状态。 | yii\validators\Validator |
isEmpty() | 检测指定的值是否为空。 如果它是一个 null,一个空的数组,或者一个空字符串,那么它会被认为是一个空值。 注意这个方法和 PHP 的 empty() 函数不同,当值为 0 时,它会返还 false 。(非空值) | yii\validators\Validator |
off() | Detaches an existing event handler from this component. | yii\base\Component |
on() | Attaches an event handler to an event. | yii\base\Component |
trigger() | Triggers an event. | yii\base\Component |
validate() | 校验一个指定的值。 你可以使用这个方法在数据模型上下文之外的地方校验一个值。 | yii\validators\Validator |
validateAttribute() | 校验单个属性。 子类必须实现这个方法以实现具体的校验逻辑。 | yii\validators\Validator |
validateAttributes() | 校验指定的对象。 | yii\validators\Validator |
受保护的方法
方法 | 描述 | 被定义在 |
---|---|---|
formatMessage() | 使用 I18N 格式化消息,或者只是简单的 strtr ,如果 \Yii::$app 不可用的话。 |
yii\validators\Validator |
validateValue() | 校验一个值。 一个校验类可以实现这个方法,以支持在数据模型上下文之外的地方支持数据校验。 | yii\validators\Validator |
属性详情
属性名称列表.
将要被这个校验器校验的属性名,或者列表。如果多属性,请通过一个数组设置它们。 对于单属性,你可以使用一个字符串,也可以使用一个数组指定。
List of built-in validators (name => class or configuration)
是否启用这个校验器的客户端校验。 实际的校验过程是通过 clientValidateAttribute() 返回的 JS 代码来执行。 如果这个方法返回 null, 即使这个属性值为 true ,也不会执行任何客户端校验。
校验器不应该应用的情景。 对于多情景,请以一个数组的形式指定它们。对于单情景,你可以使用一个字符串或者一个数组。
用于替换默认的 isEmpty() 空值校验方法,
如果没有设置,将会使用 isEmpty() 做空值校验。
这个函数的声明应该为 function ($value)
,
它的返回值为一个代表这个值是否为空的布尔值。
用户定义的错误消息。 它可以使用如下的占位符,并将会相应地被校验器替换:
{attribute}
: 被校验的属性标签{value}
: 被校验的属性值
注意:有一些校验器会引入其他的属性用于指定的校验条件未满足时的错误消息。 关于这些属性的具体详情,请参考具体的类 API 文档。 通常, 这些属性代表最重要的校验规则未满足时的所触发的主要错误消息。
校验器被应用的情景。 对于多情景,请以一个数组的形式指定它们。对于单情景,你可以使用一个字符串或者一个数组。
当被校验的属性值为 null 或者空字符串时, 是否该跳过这个校验规则。
当被校验的属性根据之前的校验规则已经有一些校验错误时,这个校验规则是否应该被跳过。 默认为 true。
一个PHP函数调用,它的返回值将会决定这个校验器是否被应用。
这个函数的声明应该为 function ($model, $attribute)
,其中 $model
和 $attribute
代表被校验的模型和属性。
这个函数应该返回一个布尔值。
这个属性主要用于支持服务端条件校验。 如果这个属性没有被设置,这个校验器将会总是在服务端执行校验。
以下是一个示例,只有当前选择的国家为 USA 时,才会在服务端执行此校验器:
function ($model) {
return $model->country == Country::USA;
}
参见 $whenClient.
这是一个 JS 函数,它的返回值将会决定校验器是否在客户端执行。
这个函数的声明应该为 function (attribute, value)
,
其中 attribute
代表被要被校验的属性对象(参考: clientValidateAttribute()),
value
是属性当前值。
这个属性主要用于支持客户端条件校验。 如果这个属性没有被设置,这个校验器将会总是在客户端执行校验。
以下是一个示例,只有当前选择的国家为 USA 时,才会在客户端执行此校验器:
function (attribute, value) {
return $('#country').val() === 'USA';
}
参见 $when.
方法详情
添加指定属性的错误到模型对象中。 这是一个帮助方法用于执行消息的选择和国际化。
public void addError($model, $attribute, $message, $params = []) | ||
$model | yii\base\Model | 被校验的数据模型 |
$attribute | string | 被校验的属性 |
$message | string | 错误消息 |
$params | array | 用于替换错误消息中占位符的变量 |
返回可用于客户端校验的 JS 代码。
调用 getClientOptions() 来生成客户端校验数组。
如果这个校验器可以支持客户端校验的话, 你可以重写这个方法来返回 JS 校验代码。
如下预定义 JS 变量可以用于校验代码中:
attribute
: 描述被校验属性的对象value
: 被校验的值messages
: 保存属性校验错误消息的数组deferred
: 保存 deferred 对象的数组用于异步执行校验$form
: jQuery 对象用于保存表单元素
attribute
包含如下属性:
id
: 唯一 ID 用于在表单中标识这个属性(例如: "loginform-username")name
: 属性名称或表达式(例如:表单输入时,可以为 "[0]content" )container
: 输入容器的 jQuery 选择器input
: 表单上下文输入字段的 jQuery 选择器error
: 容器上下文错误标签的 jQuery 选择器status
: 输入字段的状态,0:空的,没有输入,1:校验过了,2:待校验,3:校验中
参见:
public string|null clientValidateAttribute($model, $attribute, $view) | ||
$model | yii\base\Model | 被校验的数据模型。 |
$attribute | string | 待校验的属性名称 |
$view | yii\web\View | 将要被用于渲染视图或者视图文件的视图对象 包含应用校验器的表单模型。 |
return | string|null | 客户端校验脚本。如果校验器不支持的话,返回 null。 客户端校验。 |
---|
创建校验器对象。
public static yii\validators\Validator createValidator($type, $model, $attributes, $params = []) | ||
$type | string|Closure | 校验器类型,可以为:
|
$model | yii\base\Model | 被校验的数据模型。 |
$attributes | array|string | 被校验的属性。它可以是一个属性名称数组, 也可以是逗号分隔的属性名称字符串。 |
$params | array | 校验器属性的初始值。 |
return | yii\validators\Validator | The validator |
---|
使用 I18N 格式化消息,或者只是简单的 strtr ,如果 \Yii::$app
不可用的话。
protected string formatMessage($message, $params) | ||
$message | string | |
$params | array |
返回去除开头 !
的属性名称。
public array getAttributeNames() | ||
return | array | 属性名称列表. |
---|
返回客户端校验参数。 这个方法通常在 clientValidateAttribute() 中调用。 你可以改写这个方法用于修改传给客户端校验的参数。
public array getClientOptions($model, $attribute) | ||
$model | yii\base\Model | 被校验的模型。 |
$attribute | string | 被校验的属性名称。 |
return | array | 客户端校验参数。 |
---|
public void getValidationAttributes($attributes = null) | ||
$attributes |
Initializes the object.
This method is invoked at the end of the constructor after the object is initialized with the given configuration.
public void init() |
返回一个值代表当前校验器在当前情景和属性下是否是激活状态。
一个校验器是激活状态,如果:
- 这个校验器的
on
属性是空的,或者 - 这个校验器的
on
属性包含指定的情景。
public boolean isActive($scenario) | ||
$scenario | string | 情景名称 |
return | boolean | 是否这个校验器可以在该情景下应用。 |
---|
检测指定的值是否为空。 如果它是一个 null,一个空的数组,或者一个空字符串,那么它会被认为是一个空值。 注意这个方法和 PHP 的 empty() 函数不同,当值为 0 时,它会返还 false 。(非空值)
public boolean isEmpty($value) | ||
$value | mixed | 待检测的值 |
return | boolean | 值是否为空 |
---|
校验一个指定的值。 你可以使用这个方法在数据模型上下文之外的地方校验一个值。
public boolean validate($value, &$error = null) | ||
$value | mixed | 被校验的数据值。 |
$error | string | 如果校验失败,被返回的错误消息 |
return | boolean | 数据是否合法 |
---|
校验单个属性。 子类必须实现这个方法以实现具体的校验逻辑。
public void validateAttribute($model, $attribute) | ||
$model | yii\base\Model | 被校验的数据模型对象。 |
$attribute | string | 被校验的属性名称。 |
校验指定的对象。
public void validateAttributes($model, $attributes = null) | ||
$model | yii\base\Model | 被校验的数据模型 |
$attributes | array|string|null | 被校验的属性列表 注意,如果一个属性没有和校验器关联,它会被忽略。 如果这个参数为 null,$attributes 里面的每个属性都会被校验。 |
校验一个值。 一个校验类可以实现这个方法,以支持在数据模型上下文之外的地方支持数据校验。
protected array|null validateValue($value) | ||
$value | mixed | 被校验的数据值。 |
return | array|null | 错误消息,和可用于替换错误消息中占位符的参数。
对于这个例子 如果数据是合法的,返回 null。 |
---|---|---|
throws | yii\base\NotSupportedException | 如果校验器不支持模型外数据校验。 |