CFileValidator


system.validators
继承 class CFileValidator » CValidator » CComponent
源自 1.0
版本 $Id: CFileValidator.php 3491 2011-12-17 05:17:57Z jefftulsa $
源码
CFileValidator验证一个属性是否接收到一个有效的上传文件。

它使用模型类的属性名检索上传文件的信息,然后检验这个 文件是否已被成功上传,上传文件的大小是否未超过限制, 上传文件的类型是否被允许。

如果此属性之前未被赋值,此验证器将尝试提取上传的数据。 请注意:如果使用了表格式输入,此动作将不会被完成:
 foreach($models as $i=>$model)
    $model->attribute = CUploadedFile::getInstance($model, "[$i]attribute");
请注意:你必须使用CUploadedFile::getInstances 来完成多文件上传。

当在一个活动记录中使用CFileValidator,通常会使用类似下面的代码:
 if($model->save())
 {
    // single upload
    $model->attribute->saveAs($path);
    // multiple upload
    foreach($model->attribute as $file)
       $file->saveAs($path);
 }


你可以使用CFileValidator来验证文件的属性。

除了使用message属性来设置自定义错误提示信息之外, 根据不同的验证情景模式,你还可以为CFileValidator设置一些, 不同的自定义错误提示信息。如果上传文件太大,你可以使用 tooLarge属性来定义错误提示信息。类似地有tooSmallwrongTypetooMany。自定义的错误提示信息 可以包括占位符,占位符将被实际内容替换。除了所有验证器均 可识别的“{attribute}”占位符(参见CValidator)外, CFileValidator还允许指定下列占位符:

公共属性

属性 类型 描述 定义在
allowEmpty boolean 此属性是否需要上传一个文件。 默认值是false,表示需要上传一个文件。 CFileValidator
attributes array 需要被验证的属性的列表。 CValidator
builtInValidators array 内置验证器列表 (name=>class) CValidator
enableClientValidation boolean 是否执行客户端验证。默认值为true。 参见CActiveForm::enableClientValidation以了解更多关于客户端验证的细节。 CValidator
maxFiles integer 给定属性可处理的最大文件数。 默认值是1,表示单个文件上传。通过设置一个较高的数值, 可以进行多文件上传。 CFileValidator
maxSize integer 上传文件允许的最大字节数。 默认值为null,表示不限制。 注意:允许的最大字节数也同时受 'upload_max_filesize' INI 设置值 和 'MAX_FILE_SIZE' 隐藏字段值的影响。 CFileValidator
message string 用户自定义的错误提示信息。不同的验证器可以在该信息中 定义各种占位符(将被实际值替换)。占位符“{attribute}”可以被所有 验证器识别,它会被使用属性的标签来替换。 CValidator
minSize integer 上传文件允许的最小字节数。 默认值为null,表示不限制。 CFileValidator
on array 验证器将被应用到的情景模式的列表。 数组的键-值都是情景模式的名称。 CValidator
safe boolean 进行整块赋值是是否考虑此验证器中列出的属性的安全性。 默认值为true。 CValidator
skipOnError boolean 如果当前属性已经存在验证错误,这个验证规则 是否跳过。默认值是false。 CValidator
tooLarge string 上传文件太大的错误提示信息。 CFileValidator
tooMany string 上传文件数超过限制的 错误提示信息。 CFileValidator
tooSmall string 上传文件太小的错误提示信息。 CFileValidator
types mixed 允许被上传的文件扩展名的列表。 可以是一个数组,也可以是一个由被允许的文件扩展名 组成的字符串,扩展名之间使用空格或逗号分隔 (例如:"gif, jpg")。文件扩展名是大小写敏感的。 默认值是null,表示所有类型都被允许。 CFileValidator
wrongType string 上传文件的扩展名不包含在extensions 中的错误提示信息。 CFileValidator

受保护属性

属性 类型 描述 定义在
sizeLimit integer 返回允许的上传文件最大字节数 CFileValidator

公共方法

方法 描述 定义在
__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
emptyAttribute() 通知终端用户出现了空白属性的错误 CFileValidator
getSizeLimit() 返回允许的上传文件最大字节数 CFileValidator
isEmpty() 检测给定值是否为空。 CValidator
validateAttribute() 为传入对象的属性赋值,然后使用validateFile进行验证。 CFileValidator
validateFile() 内部验证一个文件对象。 CFileValidator

属性详细

allowEmpty 属性
public boolean $allowEmpty;

此属性是否需要上传一个文件。 默认值是false,表示需要上传一个文件。

maxFiles 属性
public integer $maxFiles;

给定属性可处理的最大文件数。 默认值是1,表示单个文件上传。通过设置一个较高的数值, 可以进行多文件上传。

maxSize 属性
public integer $maxSize;

上传文件允许的最大字节数。 默认值为null,表示不限制。 注意:允许的最大字节数也同时受 'upload_max_filesize' INI 设置值 和 'MAX_FILE_SIZE' 隐藏字段值的影响。

参见

minSize 属性
public integer $minSize;

上传文件允许的最小字节数。 默认值为null,表示不限制。

参见

sizeLimit 属性 只读
protected integer getSizeLimit()

返回允许的上传文件最大字节数 最大字节数由以下三个因素共同决定:

  • php.ini配置文件中的“upload_max_filesize”设置
  • 隐藏字段“MAX_FILE_SIZE”
  • maxSize
tooLarge 属性
public string $tooLarge;

上传文件太大的错误提示信息。

参见

tooMany 属性
public string $tooMany;

上传文件数超过限制的 错误提示信息。

tooSmall 属性
public string $tooSmall;

上传文件太小的错误提示信息。

参见

types 属性
public mixed $types;

允许被上传的文件扩展名的列表。 可以是一个数组,也可以是一个由被允许的文件扩展名 组成的字符串,扩展名之间使用空格或逗号分隔 (例如:"gif, jpg")。文件扩展名是大小写敏感的。 默认值是null,表示所有类型都被允许。

wrongType 属性
public string $wrongType;

上传文件的扩展名不包含在extensions 中的错误提示信息。

方法详细

emptyAttribute() 方法
protected void emptyAttribute(CModel $object, string $attribute)
$object CModel 需要验证的对象
$attribute string 需要验证的属性
protected function emptyAttribute($object$attribute)
{
    if(!
$this->allowEmpty)
    {
        
$message=$this->message!==null?$this->message Yii::t('yii','{attribute} cannot be blank.');
        
$this->addError($object,$attribute,$message);
    }
}

通知终端用户出现了空白属性的错误

getSizeLimit() 方法
protected integer getSizeLimit()
{return} integer 上传文件的字节数。
protected function getSizeLimit()
{
    
$limit=ini_get('upload_max_filesize');
    
$limit=$this->sizeToBytes($limit);
    if(
$this->maxSize!==null && $limit>&& $this->maxSize<$limit)
        
$limit=$this->maxSize;
    if(isset(
$_POST['MAX_FILE_SIZE']) && $_POST['MAX_FILE_SIZE']>&& $_POST['MAX_FILE_SIZE']<$limit)
        
$limit=$_POST['MAX_FILE_SIZE'];
    return 
$limit;
}

返回允许的上传文件最大字节数 最大字节数由以下三个因素共同决定:

  • php.ini配置文件中的“upload_max_filesize”设置
  • 隐藏字段“MAX_FILE_SIZE”
  • maxSize
validateAttribute() 方法
protected void validateAttribute(CModel $object, string $attribute)
$object CModel 需要验证的对象
$attribute string 需要验证的属性
protected function validateAttribute($object$attribute)
{
    if(
$this->maxFiles 1)
    {
        
$files=$object->$attribute;
        if(!
is_array($files) || !isset($files[0]) || !$files[0] instanceof CUploadedFile)
            
$files CUploadedFile::getInstances($object$attribute);
        if(array()===
$files)
            return 
$this->emptyAttribute($object$attribute);
        if(
count($files) > $this->maxFiles)
        {
            
$message=$this->tooMany!==null?$this->tooMany Yii::t('yii''{attribute} cannot accept more than {limit} files.');
            
$this->addError($object$attribute$message, array('{attribute}'=>$attribute'{limit}'=>$this->maxFiles));
        }
        else
            foreach(
$files as $file)
                
$this->validateFile($object$attribute$file);
    }
    else
    {
        
$file $object->$attribute;
        if(!
$file instanceof CUploadedFile)
        {
            
$file CUploadedFile::getInstance($object$attribute);
            if(
null===$file)
                return 
$this->emptyAttribute($object$attribute);
        }
        
$this->validateFile($object$attribute$file);
    }
}

为传入对象的属性赋值,然后使用validateFile进行验证。 如果存在任何验证错误,错误提示信息将被添加到对象中。

validateFile() 方法
protected void validateFile(CModel $object, string $attribute, CUploadedFile $file)
$object CModel 需要验证的对象
$attribute string 需要验证的属性
$file CUploadedFile 上传的文件,基于一个规则的集合对其进行检测
protected function validateFile($object$attribute$file)
{
    if(
null===$file || ($error=$file->getError())==UPLOAD_ERR_NO_FILE)
        return 
$this->emptyAttribute($object$attribute);
    else if(
$error==UPLOAD_ERR_INI_SIZE || $error==UPLOAD_ERR_FORM_SIZE || $this->maxSize!==null && $file->getSize()>$this->maxSize)
    {
        
$message=$this->tooLarge!==null?$this->tooLarge Yii::t('yii','The file "{file}" is too large. Its size cannot exceed {limit} bytes.');
        
$this->addError($object,$attribute,$message,array('{file}'=>$file->getName(), '{limit}'=>$this->getSizeLimit()));
    }
    else if(
$error==UPLOAD_ERR_PARTIAL)
        throw new 
CException(Yii::t('yii','The file "{file}" was only partially uploaded.',array('{file}'=>$file->getName())));
    else if(
$error==UPLOAD_ERR_NO_TMP_DIR)
        throw new 
CException(Yii::t('yii','Missing the temporary folder to store the uploaded file "{file}".',array('{file}'=>$file->getName())));
    else if(
$error==UPLOAD_ERR_CANT_WRITE)
        throw new 
CException(Yii::t('yii','Failed to write the uploaded file "{file}" to disk.',array('{file}'=>$file->getName())));
    else if(
defined('UPLOAD_ERR_EXTENSION') && $error==UPLOAD_ERR_EXTENSION)  // available for PHP 5.2.0 or above
        
throw new CException(Yii::t('yii','File upload was stopped by extension.'));

    if(
$this->minSize!==null && $file->getSize()<$this->minSize)
    {
        
$message=$this->tooSmall!==null?$this->tooSmall Yii::t('yii','The file "{file}" is too small. Its size cannot be smaller than {limit} bytes.');
        
$this->addError($object,$attribute,$message,array('{file}'=>$file->getName(), '{limit}'=>$this->minSize));
    }

    if(
$this->types!==null)
    {
        if(
is_string($this->types))
            
$types=preg_split('/[\s,]+/',strtolower($this->types),-1,PREG_SPLIT_NO_EMPTY);
        else
            
$types=$this->types;
        if(!
in_array(strtolower($file->getExtensionName()),$types))
        {
            
$message=$this->wrongType!==null?$this->wrongType Yii::t('yii','The file "{file}" cannot be uploaded. Only files with these extensions are allowed: {extensions}.');
            
$this->addError($object,$attribute,$message,array('{file}'=>$file->getName(), '{extensions}'=>implode(', ',$types)));
        }
    }
}

内部验证一个文件对象。