YII 类库手册
> YII 类库手册 > CValidator
包 system.validators
继承 abstract class CValidator » CComponent
子类 CBooleanValidator, CCaptchaValidator, CCompareValidator, CDateValidator, CDefaultValueValidator, CEmailValidator, CExistValidator, CFileValidator, CFilterValidator, CInlineValidator, CNumberValidator, CRangeValidator, CRegularExpressionValidator, CRequiredValidator, CSafeValidator, CStringValidator, CTypeValidator, CuniqueValidator, CUnsafeValidator, curlValidator
源自 1.0
版本 $Id: CValidator.php 3515 2011-12-28 12:29:24Z mDOMba $
源码
CValidator是所有验证器类的基类。

子类必须完成validateAttribute方法。

在CValidator中定义了下列属性：
  • attributes: array, 需要被验证的属性的列表；
  • message: string, 自定义的错误提示信息。它可以 包含占位符，在输出时占用符将被实际内容替换。 例如，占位符“{attribute}”将被有问题的属性的标签替换。 不同的验证器可以定义额外的占位符。
  • on: string, 指明验证器在何种情景模式（scenario）下生效。 此属性与调用CModel::validate方法时提供的“on”参数相匹配。


当使用createValidator来创建一个验证器时，可以使用以下 别名，它们可以被识别为对应的内置验证器类：
  • required: CRequiredValidator
  • filter: CFilterValidator
  • match: CRegularExpressionValidator
  • email: CEmailValidator
  • url: CUrlValidator
  • unique: CUniqueValidator
  • compare: CCompareValidator
  • length: CStringValidator
  • in: CRangeValidator
  • numerical: CNumberValidator
  • captcha: CCaptchaValidator
  • type: CTypeValidator
  • file: CFileValidator
  • default: CDefaultValueValidator
  • exist: CExistValidator
  • boolean: CBooleanValidator
  • date: CDateValidator
  • safe: CSafeValidator
  • unsafe: CUnsafeValidator

公共属性

属性 类型 描述 定义在
attributes array 需要被验证的属性的列表。 CValidator
builtInValidators array 内置验证器列表 (name=>class) CValidator
enableClientValidation boolean 是否执行客户端验证。默认值为true。 参见CActiveForm::enableClientValidation以了解更多关于客户端验证的细节。 CValidator
message string 用户自定义的错误提示信息。不同的验证器可以在该信息中 定义各种占位符（将被实际值替换）。占位符“{attribute}”可以被所有 验证器识别，它会被使用属性的标签来替换。 CValidator
on array 验证器将被应用到的情景模式的列表。 数组的键-值都是情景模式的名称。 CValidator
safe boolean 进行整块赋值是是否考虑此验证器中列出的属性的安全性。 默认值为true。 CValidator
skipOnError boolean 如果当前属性已经存在验证错误，这个验证规则 是否跳过。默认值是false。 CValidator

公共方法

方法 描述 定义在
__call() 如果类中没有调的方法名，则调用这个方法。 CComponent
__get() 返回一个属性值、一个事件处理程序列表或一个行为名称。 CComponent
__isset() 检查一个属性是否为null。 CComponent
__set() 设置一个组件的属性值。 CComponent
__unset() 设置一个组件的属性为null。 CComponent
applyTo() 返回值指定此验证器是否应用到指定的情景模式。 CValidator
asa() 返回这个名字的行为对象。 CComponent
attachBehavior() 附加一个行为到组件。 CComponent
attachBehaviors() 附加一个行为列表到组件。 CComponent
attachEventHandler() 为事件附加一个事件处理程序。 CComponent
canGetProperty() 确定属性是否可读。 CComponent
canSetProperty() 确定属性是否可写。 CComponent
clientValidateAttribute() 返回执行客户端验证所需的JavaScript脚本。 CValidator
createValidator() 创建一个验证器对象。 CValidator
detachBehavior() 从组件中分离一个行为。 CComponent
detachBehaviors() 从组件中分离所有行为。 CComponent
detachEventHandler() 分离一个存在的事件处理程序。 CComponent
disableBehavior() 禁用一个附加行为。 CComponent
disableBehaviors() 禁用组件附加的所有行为。 CComponent
enableBehavior() 启用一个附加行为。 CComponent
enableBehaviors() 启用组件附加的所有行为。 CComponent
evaLuateExpression() 计算一个PHP表达式，或根据组件上下文执行回调。 CComponent
getEventHandlers() 返回一个事件的附加处理程序列表。 CComponent
hasEvent() 确定一个事件是否定义。 CComponent
hasEventHandler() 检查事件是否有附加的处理程序。 CComponent
hasProperty() 确定属性是否被定义。 CComponent
raiseEvent() 发起一个事件。 CComponent
validate() 验证给定的对象。 CValidator

受保护方法

方法 描述 定义在
addError() 添加关于指定属性的一个错误提示信息到活动记录中。 CValidator
isEmpty() 检测给定值是否为空。 CValidator
validateAttribute() 验证一个单一属性。 CValidator

属性详细

attributes 属性
public array $attributes;

需要被验证的属性的列表。

builtInValidators 属性
public static array $builtInValidators;

内置验证器列表 (name=>class)

enableClientValidation 属性 （可用自 v1.1.7）
public boolean $enableClientValidation;

是否执行客户端验证。默认值为true。 参见CActiveForm::enableClientValidation以了解更多关于客户端验证的细节。

message 属性
public string $message;

用户自定义的错误提示信息。不同的验证器可以在该信息中 定义各种占位符（将被实际值替换）。占位符“{attribute}”可以被所有 验证器识别，它会被使用属性的标签来替换。

on 属性
public array $on;

验证器将被应用到的情景模式的列表。 数组的键-值都是情景模式的名称。

safe 属性 （可用自 v1.1.4）
public boolean $safe;

进行整块赋值是是否考虑此验证器中列出的属性的安全性。 默认值为true。

skipOnError 属性 （可用自 v1.1.1）
public boolean $skipOnError;

如果当前属性已经存在验证错误，这个验证规则 是否跳过。默认值是false。

方法详细

addError() 方法
protected void addError(CModel $object, string $attribute, string $message, array $params=array ( ))
$object CModel 需要验证的数据对象
$attribute string 需要验证的属性
$message string 错误提示信息
$params array 在错误提示信息中各个占位符的值。 

protected function addError($object,$attribute,$message,$params=array())
{
    $params['{attribute}']=$object->getAttributeLabel($attribute);
    $object->addError($attribute,strtr($message,$params));
}

添加关于指定属性的一个错误提示信息到活动记录中。 这是一个执行消息选择和国际化的助手类。

applyTo() 方法
public boolean applyTo(string $scenario)
$scenario string 情景模式名称
{return} boolean 此验证器是否应用到指定的情景模式。 

public function applyTo($scenario)
{
    return empty($this->on) || isset($this->on[$scenario]);
}

返回值指定此验证器是否应用到指定的情景模式。 一个验证器应用到一个情景模式需要满足以下条件之一：

  • 此验证器的“on”属性值为空
  • 此验证器的“on”属性值包含指定的情景模式
clientValidateAttribute() 方法 （可用自 v1.1.7）
public string clientValidateAttribute(CModel $object, string $attribute)
$object CModel 需要被验证的数据对象
$attribute string 需要验证的属性名称
{return} string 客户端验证脚本。如果此验证器不支持客户端验证，则返回Null。 

public function clientValidateAttribute($object,$attribute)
{
}

返回执行客户端验证所需的JavaScript脚本。 如果验证器不支持客户端验证，请不要覆盖此方法。 有两个预定的JavaScript变量可以使用：

  • value: 需要被验证的值
  • messages: 用于保存被验证的值的错误提示信息的数组

参见

  • CActiveForm::enableClientValidation
createValidator() 方法
public static CValidator createValidator(string $name, CModel $object, mixed $attributes, array $params=array ( ))
$name string 验证器的名称或类。
$object CModel 被验证的数据模型对象，它可以包含内联的验证方法。
$attributes mixed 被验证的属性的列表，它可以是一个由属性名称 组成的数组，也可以是一个用逗号分隔的属性名称组成的字符串。
$params array 应用到验证器属性的初始值。
{return} CValidator 生成的验证器实例 

public static function createValidator($name,$object,$attributes,$params=array())
{
    if(is_string($attributes))
        $attributes=preg_split('/[\s,]+/',$attributes,-1,PREG_SPLIT_NO_EMPTY);

    if(isset($params['on']))
    {
        if(is_array($params['on']))
            $on=$params['on'];
        else
            $on=preg_split('/[\s,]+/',$params['on'],-1,PREG_SPLIT_NO_EMPTY);
    }
    else
        $on=array();

    if(method_exists($object,$name))
    {
        $validator=new CInlineValidator;
        $validator->attributes=$attributes;
        $validator->method=$name;
        if(isset($params['clientValidate']))
        {
            $validator->clientValidate=$params['clientValidate'];
            unset($params['clientValidate']);
        }
        $validator->params=$params;
        if(isset($params['skipOnError']))
            $validator->skipOnError=$params['skipOnError'];
    }
    else
    {
        $params['attributes']=$attributes;
        if(isset(self::$builtInValidators[$name]))
            $className=Yii::import(self::$builtInValidators[$name],true);
        else
            $className=Yii::import($name,true);
        $validator=new $className;
        foreach($params as $name=>$value)
            $validator->$name=$value;
    }

    $validator->on=empty($on) ? array() : array_combine($on,$on);

    return $validator;
}

创建一个验证器对象。

isEmpty() 方法
protected boolean isEmpty(mixed $value, boolean $trim=false)
$value mixed 需要检测的值
$trim boolean 当检测字符串是否为空时，是否首先执行修整。默认值为false。
{return} boolean 给定值是否为空 

protected function isEmpty($value,$trim=false)
{
    return $value===null || $value===array() || $value==='' || $trim && is_scalar($value) && trim($value)==='';
}

检测给定值是否为空。 当一个值为null，或空数组，或修整后为空的字符串时，我们认为此值为空。 注意：此方法与PHP的empty()方法不同，当值为0时它返回false。

validate() 方法
public void validate(CModel $object, array $attributes=NULL)
$object CModel 需要被验证的数据模型对象
$attributes array 被验证的属性的列表。默认值是null， 表示attributes中列出的所有属性都将被验证。 

public function validate($object,$attributes=null)
{
    if(is_array($attributes))
        $attributes=array_intersect($this->attributes,$attributes);
    else
        $attributes=$this->attributes;
    foreach($attributes as $attribute)
    {
        if(!$this->skipOnError || !$object->hasErrors($attribute))
            $this->validateAttribute($object,$attribute);
    }
}

验证给定的对象。

validateAttribute() 方法
abstract protected void validateAttribute(CModel $object, string $attribute)
$object CModel 被验证的数据模型对象
$attribute string 被验证的属性名称 

abstract protected function validateAttribute($object,$attribute);

验证一个单一属性。 此方法需要由子类覆盖。

上一篇：