CFileValidator

所有包 | 属性 | 方法

包	system.validators
继承	class CFileValidator » CValidator » CComponent
源自	1.0
版本	$Id: CFileValidator.php 3491 2011-12-17 05:17:57Z jefftulsa $
源码	framework/validators/CFileValidator.php

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属性来定义错误提示信息。类似地有tooSmall， wrongType和tooMany。自定义的错误提示信息可以包括占位符，占位符将被实际内容替换。除了所有验证器均可识别的“{attribute}”占位符（参见CValidator）外， CFileValidator还允许指定下列占位符：

{file}: 使用文件名替换。
{limit}: 当使用tooLarge时，使用maxSize 替换；当使用tooSmall时，使用maxSize替换；当使用tooMany时，使用maxFiles替换。
{extensions}: 当使用wrongType时，使用被允许的扩展名替换。

公共属性

隐藏继承属性

属性	类型	描述	定义在
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' 隐藏字段值的影响。

参见

tooLarge

minSize 属性

public integer $minSize;

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

参见

tooSmall

sizeLimit 属性只读

protected integer getSizeLimit()

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

php.ini配置文件中的“upload_max_filesize”设置
隐藏字段“MAX_FILE_SIZE”
maxSize

tooLarge 属性

public string $tooLarge;

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

参见

maxSize

tooMany 属性

public string $tooMany;

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

tooSmall 属性

public string $tooSmall;

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

参见

minSize

types 属性

public mixed $types;

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

wrongType 属性

public string $wrongType;

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

方法详细

emptyAttribute() 方法

protected void emptyAttribute(CModel $object, string $attribute)
$object	CModel	需要验证的对象
$attribute	string	需要验证的属性

源码： framework/validators/CFileValidator.php#204 (显示)


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	上传文件的字节数。

源码： framework/validators/CFileValidator.php#224 (显示)


protected function getSizeLimit()
{
    $limit=ini_get('upload_max_filesize');
    $limit=$this->sizeToBytes($limit);
    if($this->maxSize!==null && $limit>0 && $this->maxSize<$limit)
        $limit=$this->maxSize;
    if(isset($_POST['MAX_FILE_SIZE']) && $_POST['MAX_FILE_SIZE']>0 && $_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	需要验证的属性

源码： framework/validators/CFileValidator.php#124 (显示)


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	上传的文件，基于一个规则的集合对其进行检测

源码： framework/validators/CFileValidator.php#161 (显示)


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)));
        }
    }
}

内部验证一个文件对象。