包 | system.validators |
---|---|
继承 | class CFileValidator » CValidator » CComponent |
源自 | 1.0 |
版本 | $Id: CFileValidator.php 3491 2011-12-17 05:17:57Z jefftulsa $ |
源码 |
CFileValidator验证一个属性是否接收到一个有效的上传文件。
它使用模型类的属性名检索上传文件的信息,然后检验这个 文件是否已被成功上传,上传文件的大小是否未超过限制, 上传文件的类型是否被允许。
如果此属性之前未被赋值,此验证器将尝试提取上传的数据。 请注意:如果使用了表格式输入,此动作将不会被完成:
当在一个活动记录中使用CFileValidator,通常会使用类似下面的代码:
你可以使用CFileValidator来验证文件的属性。
除了使用message属性来设置自定义错误提示信息之外, 根据不同的验证情景模式,你还可以为CFileValidator设置一些, 不同的自定义错误提示信息。如果上传文件太大,你可以使用 tooLarge属性来定义错误提示信息。类似地有tooSmall, wrongType和tooMany。自定义的错误提示信息 可以包括占位符,占位符将被实际内容替换。除了所有验证器均 可识别的“{attribute}”占位符(参见CValidator)外, 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 | 需要验证的属性 |
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>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 | 需要验证的属性 |
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)));
}
}
}
内部验证一个文件对象。