没有命名空间的类 yii yii\base yii\behaviors yii\caching yii\captcha yii\console yii\console\controllers yii\console\widgets yii\data yii\db yii\db\conditions yii\db\cubrid yii\db\cubrid\conditions yii\db\mssql yii\db\mssql\conditions yii\db\mysql yii\db\oci yii\db\oci\conditions yii\db\pgsql yii\db\sqlite yii\db\sqlite\conditions yii\di yii\filters yii\filters\auth yii\grid yii\helpers yii\i18n yii\log yii\mail yii\mutex yii\rbac yii\rest yii\test yii\validators yii\web yii\widgets

Class yii\validators\FileValidator

继承yii\validators\FileValidator » yii\validators\Validator » yii\base\Component » yii\base\BaseObject
实现yii\base\Configurable
子类yii\validators\ImageValidator
可用版本自2.0
源码 https://github.com/yiichina/yii2/blob/api/framework/validators/FileValidator.php

FileValidator 校验一个指定的属性接受的是一个合法的上传文件。

注意你需要开启 fileinfo PHP扩展。

公共属性

隐藏继承的属性

属性类型描述被定义在
$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
$checkExtensionByMimeType boolean 是否检查文件类型(扩展名)和 mime-type 是否符合。 如果 mime-type 得到的扩展名和文件名称扩展名不一致,文件会被认为非法。 yii\validators\FileValidator
$enableClientValidation boolean 是否启用这个校验器的客户端校验。 实际的校验过程是通过 clientValidateAttribute() 返回的 JS 代码来执行。 如果这个方法返回 null, 即使这个属性值为 true ,也不会执行任何客户端校验。 yii\validators\Validator
$except array|string 校验器不应该应用的情景。 对于多情景,请以一个数组的形式指定它们。对于单情景,你可以使用一个字符串或者一个数组。 yii\validators\Validator
$extensions array|string 可上传的文件扩展名列表。 它可以是一个数组, 或者一个由空格或者逗号分隔的字符串(例如:"gif, jpg")。 扩展名称大小写不敏感,默认为 null , 代表允许所有的文件扩展名。 yii\validators\FileValidator
$isEmpty callable 用于替换默认的 isEmpty() 空值校验方法, 如果没有设置,将会使用 isEmpty() 做空值校验。 这个函数的声明应该为 function ($value), 它的返回值为一个代表这个值是否为空的布尔值。 yii\validators\Validator
$maxFiles integer 指定的属性可最多持有的文件数量。 默认为1,代表上传单文件。 你可以设置一个大一点的值,这样允许同时上传多个文件。 设置为 0 意味着同时上传的文件数目没有限制。 > 注意:同时上传的最大文件数量同样受 max_file_uploads 限制, 其默认值为 20。 yii\validators\FileValidator
$maxSize integer 上传文件的最大字节数, 默认为null,代表无限制。 注意:大小限制同样会受 upload_max_filesizepost_max_size INI 参数以及 MAX_FILE_SIZE 隐藏字段值影响。 更多详情参考 getSizeLimit() yii\validators\FileValidator
$message string 一个文件没有被正确上传时的错误消息。 yii\validators\FileValidator
$mimeTypes array|string 允许被上传的文件 MIME 类型列表。 它可以是一个 MIME 类型字符串数组, 或者一个由空格或者逗号分隔的字符串(例如:"text/plain, image/png")。 可以使用通配符 * 来匹配一组 MIME 类型。 例如:image/* 将会匹配所有以 image/ 开头的 MIME 类型。(例如:image/jpeg, image/png)。 MIME 类型名称大小写不敏感。默认为 null,代表允许所有的 MIME 类型。 yii\validators\FileValidator
$minFiles integer 指定的属性最少持有的文件数量。 默认为0,代表无限制。大一点的值意味着最少那么多的文件应该被上传。 yii\validators\FileValidator
$minSize integer 上传文件的最小字节数, 默认为null,代表无限制。 yii\validators\FileValidator
$on array|string 校验器被应用的情景。 对于多情景,请以一个数组的形式指定它们。对于单情景,你可以使用一个字符串或者一个数组。 yii\validators\Validator
$sizeLimit integer The size limit for uploaded files. yii\validators\FileValidator
$skipOnEmpty boolean 当被校验的属性值为 null 或者空字符串时, 是否该跳过这个校验规则。 yii\validators\Validator
$skipOnError boolean 当被校验的属性根据之前的校验规则已经有一些校验错误时,这个校验规则是否应该被跳过。 默认为 true。 yii\validators\Validator
$tooBig string 当上传文件太大时的错误消息。 你可以在消息中使用下面的这些 token : - {attribute}: the attribute name - {file}: the uploaded file name - {limit}: the maximum size allowed (see getSizeLimit()) - {formattedLimit}: the maximum size formatted with Formatter::asShortSize() yii\validators\FileValidator
$tooFew string The error message used if the count of multiple uploads less that minFiles. yii\validators\FileValidator
$tooMany string The error message used if the count of multiple uploads exceeds limit. yii\validators\FileValidator
$tooSmall string The error message used when the uploaded file is too small. yii\validators\FileValidator
$uploadRequired string 没有文件被上传的错误消息。 注意:这是校验错误消息。 为了确保文件上传是必须的,你需要设置属性 $skipOnEmpty 值为 false yii\validators\FileValidator
$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
$wrongExtension string The error message used when the uploaded file has an extension name that is not listed in $extensions. yii\validators\FileValidator
$wrongMimeType string The error message used when the file has an mime type that is not allowed by $mimeTypes property. yii\validators\FileValidator

公共方法

隐藏继承的方法

方法描述被定义在
__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\FileValidator
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\FileValidator
getSizeLimit() 返回允许上传文件的最大大小。 yii\validators\FileValidator
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\FileValidator
isActive() 返回一个值代表当前校验器在当前情景和属性下是否是激活状态。 yii\validators\Validator
isEmpty() 检测指定的值是否为空。 如果它是一个 null,一个空的数组,或者一个空字符串,那么它会被认为是一个空值。 注意这个方法和 PHP 的 empty() 函数不同,当值为 0 时,它会返还 false 。(非空值) yii\validators\FileValidator
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\FileValidator
validateAttributes() 校验指定的对象。 yii\validators\Validator

受保护的方法

隐藏继承的方法

方法描述被定义在
formatMessage() 使用 I18N 格式化消息,或者只是简单的 strtr ,如果 \Yii::$app 不可用的话。 yii\validators\Validator
validateExtension() 根据当前校验器配置检查指定的上传文件是否含有正确的类型(扩展) yii\validators\FileValidator
validateMimeType() 检查 $file 的 mimeType 是否在 $mimeTypes 属性列表中。 yii\validators\FileValidator
validateValue() 校验一个值。 一个校验类可以实现这个方法,以支持在数据模型上下文之外的地方支持数据校验。 yii\validators\FileValidator

属性详情

$checkExtensionByMimeType 公共 属性

是否检查文件类型(扩展名)和 mime-type 是否符合。 如果 mime-type 得到的扩展名和文件名称扩展名不一致,文件会被认为非法。

$extensions 公共 属性

可上传的文件扩展名列表。 它可以是一个数组, 或者一个由空格或者逗号分隔的字符串(例如:"gif, jpg")。 扩展名称大小写不敏感,默认为 null , 代表允许所有的文件扩展名。

参见 $wrongExtension for the customized message for wrong file type.

public array|string $extensions null
$maxFiles 公共 属性

指定的属性可最多持有的文件数量。 默认为1,代表上传单文件。 你可以设置一个大一点的值,这样允许同时上传多个文件。 设置为 0 意味着同时上传的文件数目没有限制。

注意:同时上传的最大文件数量同样受 max_file_uploads 限制, 其默认值为 20。

参见:

public integer $maxFiles 1
$maxSize 公共 属性

上传文件的最大字节数, 默认为null,代表无限制。 注意:大小限制同样会受 upload_max_filesizepost_max_size INI 参数以及 MAX_FILE_SIZE 隐藏字段值影响。 更多详情参考 getSizeLimit()

参见:

public integer $maxSize null
$message 公共 属性

一个文件没有被正确上传时的错误消息。

public string $message null
$mimeTypes 公共 属性

允许被上传的文件 MIME 类型列表。 它可以是一个 MIME 类型字符串数组, 或者一个由空格或者逗号分隔的字符串(例如:"text/plain, image/png")。 可以使用通配符 * 来匹配一组 MIME 类型。 例如:image/* 将会匹配所有以 image/ 开头的 MIME 类型。(例如:image/jpeg, image/png)。 MIME 类型名称大小写不敏感。默认为 null,代表允许所有的 MIME 类型。

参见 $wrongMimeType for the customized message for wrong MIME type.

public array|string $mimeTypes null
$minFiles 公共 属性 (自版本 2.0.14 可用)

指定的属性最少持有的文件数量。 默认为0,代表无限制。大一点的值意味着最少那么多的文件应该被上传。

参见 $tooFew for the customized message when too few files are uploaded.

public integer $minFiles 0
$minSize 公共 属性

上传文件的最小字节数, 默认为null,代表无限制。

参见 $tooSmall for the customized message for a file that is too small.

public integer $minSize null
$sizeLimit 公共 只读 属性

The size limit for uploaded files.

$tooBig 公共 属性

当上传文件太大时的错误消息。 你可以在消息中使用下面的这些 token :

  • {attribute}: the attribute name
  • {file}: the uploaded file name
  • {limit}: the maximum size allowed (see getSizeLimit())
  • {formattedLimit}: the maximum size formatted with Formatter::asShortSize()
public string $tooBig null
$tooFew 公共 属性 (自版本 2.0.14 可用)

The error message used if the count of multiple uploads less that minFiles. You may use the following tokens in the message:

  • {attribute}: the attribute name
  • {limit}: the value of $minFiles
public string $tooFew null
$tooMany 公共 属性

The error message used if the count of multiple uploads exceeds limit. You may use the following tokens in the message:

  • {attribute}: the attribute name
  • {limit}: the value of $maxFiles
public string $tooMany null
$tooSmall 公共 属性

The error message used when the uploaded file is too small. You may use the following tokens in the message:

  • {attribute}: the attribute name
  • {file}: the uploaded file name
  • {limit}: the value of $minSize
  • {formattedLimit}: the value of $minSize formatted with [[\yii\i18n\Formatter::asShortSize()|Formatter::asShortSize()]
public string $tooSmall null
$uploadRequired 公共 属性

没有文件被上传的错误消息。 注意:这是校验错误消息。 为了确保文件上传是必须的,你需要设置属性 $skipOnEmpty 值为 false

public string $uploadRequired null
$wrongExtension 公共 属性

The error message used when the uploaded file has an extension name that is not listed in $extensions. You may use the following tokens in the message:

  • {attribute}: the attribute name
  • {file}: the uploaded file name
  • {extensions}: the list of the allowed extensions.
public string $wrongExtension null
$wrongMimeType 公共 属性

The error message used when the file has an mime type that is not allowed by $mimeTypes property. You may use the following tokens in the message:

  • {attribute}: the attribute name
  • {file}: the uploaded file name
  • {mimeTypes}: the value of $mimeTypes
public string $wrongMimeType null

方法详情

clientValidateAttribute() 公共 方法

返回可用于客户端校验的 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。 客户端校验。

getClientOptions() 公共 方法

返回客户端校验参数。 这个方法通常在 clientValidateAttribute() 中调用。 你可以改写这个方法用于修改传给客户端校验的参数。

public array getClientOptions($model, $attribute)
$model yii\base\Model

被校验的模型。

$attribute string

被校验的属性名称。

return array

客户端校验参数。

getSizeLimit() 公共 方法

返回允许上传文件的最大大小。

这个参数由下面四个因素决定:

  • 'upload_max_filesize' in php.ini
  • 'post_max_size' in php.ini
  • 'MAX_FILE_SIZE' hidden field
  • $maxSize
public integer getSizeLimit()
return integer

The size limit for uploaded files.

init() 公共 方法

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()
isEmpty() 公共 方法

检测指定的值是否为空。 如果它是一个 null,一个空的数组,或者一个空字符串,那么它会被认为是一个空值。 注意这个方法和 PHP 的 empty() 函数不同,当值为 0 时,它会返还 false 。(非空值)

public boolean isEmpty($value, $trim false)
$value mixed

待检测的值

$trim boolean
return boolean

值是否为空

validateAttribute() 公共 方法

校验单个属性。 子类必须实现这个方法以实现具体的校验逻辑。

public void validateAttribute($model, $attribute)
$model yii\base\Model

被校验的数据模型对象。

$attribute string

被校验的属性名称。

validateExtension() 受保护 方法

根据当前校验器配置检查指定的上传文件是否含有正确的类型(扩展)

protected boolean validateExtension($file)
$file yii\web\UploadedFile
validateMimeType() 受保护 方法 (自版本 2.0.8 可用)

检查 $file 的 mimeType 是否在 $mimeTypes 属性列表中。

参见 $mimeTypes.

protected boolean validateMimeType($file)
$file yii\web\UploadedFile
return boolean

Whether the $file mimeType is allowed

throws yii\base\InvalidConfigException
validateValue() 受保护 方法

校验一个值。 一个校验类可以实现这个方法,以支持在数据模型上下文之外的地方支持数据校验。

protected array|null validateValue($value)
$value mixed

被校验的数据值。

return array|null

错误消息,和可用于替换错误消息中占位符的参数。

if (!$valid) {
    return [$this->message, [
        'param1' => $this->param1,
        'formattedLimit' => Yii::$app->formatter->asShortSize($this->getSizeLimit()),
        'mimeTypes' => implode(', ', $this->mimeTypes),
        'param4' => 'etc...',
    ]];
}

return null;

对于这个例子 message 模板可以包含 {param1}, {formattedLimit}, {mimeTypes}, {param4}

如果数据是合法的,返回 null。

throws yii\base\NotSupportedException

如果校验器不支持模型外数据校验。