Class yii\validators\DateValidator

继承yii\validators\DateValidator » yii\validators\Validator » yii\base\Component » yii\base\BaseObject
实现yii\base\Configurable
可用自版本2.0
源代码 https://github.com/yiisoft/yii2/blob/master/framework/validators/DateValidator.php

DateValidator 验证属性是否以适当的 格式 表示日期, 时间或日期时间.

它还可以解析特定 区域设置 中的国际化日期, 例如, 当 格式 配置为使用 ICU 格式的时间格式时, 12 мая 2014.

还可以使用 $min$max 将日期限制在一定的范围内.

除了验证日期以外, 它还可以将解析后的时间戳导出为机器可读的格式, 可以使用 $timestampAttribute 进行配置.

对于包含时间信息的值(不是仅限日期值), 时区也将被调整.

$timestampAttributeFormatnull(导出为 UNIX 时间戳)或 $timestampAttributeTimeZone 时, 输入值的时区假定为 $timeZone 属性指定的时区

假设输入值的时区是由 $timeZone 属性指定的时区, 而当 $timestampAttributeFormatnull$timestampAttributeTimeZone 时, 目标时区为 UTC.

如果要避免时区转换, 请确保 $timeZone$timestampAttributeTimeZone 相同.

公共属性

隐藏继承的属性

属性类型描述定义在
$attributeNames array 属性名称. yii\validators\Validator
$attributes array|string 要由此验证器验证的属性. yii\validators\Validator
$behaviors yii\base\Behavior[] 附加到此组件的行为列表. yii\base\Component
$builtInValidators array 内置验证器列表(键值对(name => class)或配置). yii\validators\Validator
$enableClientValidation boolean 是否为此验证器启用客户端验证. yii\validators\Validator
$except array|string 验证器不应该应用的场景. yii\validators\Validator
$format string 要验证的值应该遵循的日期格式. yii\validators\DateValidator
$isEmpty callable PHP 回调函数, 它取代 isEmpty() 的默认实现. yii\validators\Validator
$locale string 用于本地化日期解析的区域设置 ID. yii\validators\DateValidator
$max integer|string 日期的上限. yii\validators\DateValidator
$maxString string 用户友好的上限值显示在错误信息中. yii\validators\DateValidator
$message string 用户定义的错误消息. yii\validators\Validator
$min integer|string 日期的下限. yii\validators\DateValidator
$minString string 用户友好的下限值显示在错误信息中. yii\validators\DateValidator
$on array|string 验证器可以应用的场景. yii\validators\Validator
$skipOnEmpty boolean 如果属性值为null或空字符串, 是否应跳过此验证规则. yii\validators\Validator
$skipOnError boolean 如果验证的属性已根据某些先前的规则已经存在某些验证错误, 是否应跳过此验证规则. yii\validators\Validator
$timeZone string 用于解析日期和时间值的时区. yii\validators\DateValidator
$timestampAttribute string 要接收解析结果的属性的名称. yii\validators\DateValidator
$timestampAttributeFormat string 填充 $timestampAttribute 时使用的格式. yii\validators\DateValidator
$timestampAttributeTimeZone string 填充 $timestampAttribute 时使用的时区. yii\validators\DateValidator
$tooBig string 用户定义的错误消息, 当值大于 $max 时使用. yii\validators\DateValidator
$tooSmall string 用户定义的错误消息, 当值小于 $min 时使用. yii\validators\DateValidator
$type string 验证器的类型. yii\validators\DateValidator
$validationAttributes array 属性名称列表. yii\validators\Validator
$when callable PHP 回调函数, 其返回值确定是否应该应用此验证器. yii\validators\Validator
$whenClient string 一个 JavaScript 函数名, 其返回值决定是否应在客户端应用此验证器. yii\validators\Validator

公共方法

隐藏继承的方法

方法描述定义在
__call() 调用不是类方法的指定的方法. yii\base\Component
__clone() 在通过克隆现有对象创建对象之后调用此方法. yii\base\Component
__construct() 构造函数. yii\base\BaseObject
__get() 返回组件属性的值. yii\base\Component
__isset() 检查属性是否已设置, 即已定义且不为null. yii\base\Component
__set() 设置组件属性的值. yii\base\Component
__unset() 将组件属性设置为null. yii\base\Component
addError() 将有关指定属性的错误添加到模型对象. yii\validators\Validator
attachBehavior() 将行为附加到此组件. yii\base\Component
attachBehaviors() 将行为列表附加到组件. yii\base\Component
behaviors() 返回此组件应该具有的行为列表. yii\base\Component
canGetProperty() 返回一个值, 指示属性是否可读取. yii\base\Component
canSetProperty() 返回一个值, 指示属性是否可设置. yii\base\Component
className() 返回此类的完全限定名称. yii\base\BaseObject
clientValidateAttribute() 返回执行客户端验证所需的 JavaScript. yii\validators\Validator
createValidator() 创建一个验证器对象. yii\validators\Validator
detachBehavior() 从组件中分离一个行为. yii\base\Component
detachBehaviors() 分离组件中的所有行为. yii\base\Component
ensureBehaviors() 确保在 behaviors() 中声明的行为已附加到此组件. yii\base\Component
getAttributeNames() 返回清理后的属性名称, 开头不带!字符. yii\validators\Validator
getBehavior() 返回指定的行为对象. yii\base\Component
getBehaviors() 返回附加到此组件的所有行为. yii\base\Component
getClientOptions() 返回客户端验证选项. yii\validators\Validator
getValidationAttributes() 返回此验证器适用的属性列表. yii\validators\Validator
hasEventHandlers() 返回一个值, 指示是否有任何处理程序附加到指定的事件. yii\base\Component
hasMethod() 返回一个值, 指示方法是否已定义. yii\base\Component
hasProperty() 返回一个值, 指示属性是否已定义. yii\base\Component
init() 初始化对象. yii\validators\DateValidator
isActive() 返回一个值, 该值指示验证器对于给定场景和属性是否处于活动状态. yii\validators\Validator
isEmpty() 检查给定值是否为空. yii\validators\Validator
off() 从该组件分离现有的事件处理程序. yii\base\Component
on() 将事件处理程序附加到事件. yii\base\Component
trigger() 触发事件. yii\base\Component
validate() 验证给定的值. yii\validators\Validator
validateAttribute() 验证单个属性. yii\validators\DateValidator
validateAttributes() 验证指定的对象. yii\validators\Validator

受保护的方法

隐藏继承的方法

方法描述定义在
formatMessage() 使用 I18N 格式化消息, 或者当\Yii::$app不可用时使用简单的strtr函数. yii\validators\Validator
parseDateValue() 将日期字符串解析为 UNIX 时间戳. yii\validators\DateValidator
validateValue() 验证一个值. yii\validators\DateValidator

常量

隐藏继承的常量

常量描述定义在
TYPE_DATE 'date' 用于将验证 类型 指定为日期值的常量, 用于使用国际短格式(intl short format)进行验证. yii\validators\DateValidator
TYPE_DATETIME 'datetime' 用于将验证 类型 指定为日期时间值的常量, 用于使用国际短格式(intl short format)进行验证. yii\validators\DateValidator
TYPE_TIME 'time' 用于将验证 类型 指定为时间值的常量, 用于使用国际短格式(intl short format)进行验证. yii\validators\DateValidator

属性详情

$format public 属性

要验证的值应该遵循的日期格式.

这可以是 ICU 手册 中描述的日期时间格式.

或者, 这可以是一个以php:为前缀的字符串, 表示可以被 PHP Datetime 类识别的格式. 有关支持的格式, 请参阅 http://php.net/manual/en/datetime.createfromformat.php.

如果未设置此属性, 则将从Yii::$app->formatter->dateFormat获取默认值, 有关详细信息, 请参阅 yii\i18n\Formatter::$dateFormat.

自版本 2.0.8 开始, 默认值将根据格式化程序类的不同格式确定, 具体取决于 $type 的值:

以下是一些示例值:

'MM/dd/yyyy' // ICU 格式的日期
'php:m/d/Y' // PHP 格式的相同日期
'MM/dd/yyyy HH:mm' // 不仅可以验证日期, 还可以验证时间

Note: 正在使用的基础日期解析器根据格式而有所不同. 如果您使用 ICU 格式并安装了 PHP intl 扩展, 则 IntlDateFormatter 用于解析输入值. 在其它所有情况下, 使用 PHP DateTime 类. IntlDateFormatter 的优势在于它可以解析像12. Mai 201512 мая 2014这样的国际日期. 而 PHP 解析器仅限于英文. 然而 PHP 解析器对输入格式更为严格, 因为它不会接受格式为php:d.m.Y12.05.05, 但是 IntlDateFormatter 将接受dd.MM.yyyy格式. 如果您需要使用 IntlDateFormatter, 则可以通过指定 最短日期 来避免此问题.

public string $format null
$locale public 属性

用于本地化日期解析的区域设置 ID.

这仅在安装 PHP intl 扩展 时才有效.

如果未设置, 将使用 formatter 的区域设置. See also yii\i18n\Formatter::$locale.

public string $locale null
$max public 属性 (可用自版本: 2.0.4)

日期的上限. 默认为null, 表示没有上限.

这可以是 unix 时间戳或表示日期时间值的字符串.

如果此属性是一个字符串, 将被用 $format 来解析它.

参见 $tooBig 用于日期过大时使用的自定义消息.

public integer|string $max null
$maxString public 属性 (可用自版本: 2.0.4)

用户友好的上限值显示在错误信息中.

如果此属性为null, 则将使用 $max 的值(在解析之前).

public string $maxString null
$min public 属性 (可用自版本: 2.0.4)

日期的下限. 默认为null, 表示没有下限.

这可以是 unix 时间戳或表示日期时间值的字符串.

如果此属性是一个字符串, 将被用 $format 来解析它.

参见 $tooSmall 用于日期过小时使用的自定义消息.

public integer|string $min null
$minString public 属性 (可用自版本: 2.0.4)

用户友好的下限值显示在错误信息中.

如果此属性为null, 则将使用 $min 的值(在解析之前).

public string $minString null
$timeZone public 属性

用于解析日期和时间值的时区.

这可以是任何可以传递给 date_default_timezone_set() 的值. eg. UTC, Europe/BerlinAmerica/Chicago.

有关可用时区, 请参考 php 手册.

如果未设置此属性, 将使用 yii\base\Application::$timeZone.

public string $timeZone null
$timestampAttribute public 属性

要接收解析结果的属性的名称.

当此属性不为null且验证成功时, 指定属性将收到解析结果.

该属性可以与正在验证的属性相同. 如果是这种情况, 成功验证后, 原始值将被时间戳值覆盖.

Note: 当使用此属性时, 输入值将被转换为 unix 时间戳, 根据定义, 该时间戳采用 UTC, 因此将执行从 input time zone 到 UTC 的转换. 当定义 $timestampAttributeFormat 时, 可以通过将 $timestampAttributeTimeZone 设置为与 UTC 不同的值来控制转换.

参见:

$timestampAttributeFormat public 属性 (可用自版本: 2.0.4)

填充 $timestampAttribute 时使用的格式.

可以使用与 $format 相同的方式指定格式.

如果未设置, $timestampAttribute 将收到一个 UNIX 时间戳.

如果未设置 $timestampAttribute, 则该属性将被忽略.

参见:

$timestampAttributeTimeZone public 属性 (可用自版本: 2.0.4)

填充 $timestampAttribute 时使用的时区. 默认为UTC.

这可以是任何可以传递给 date_default_timezone_set() 的值. eg. UTC, Europe/BerlinAmerica/Chicago.

有关可用的时区, 请参考 php 手册.

参见 $timestampAttributeFormat.

$tooBig public 属性 (可用自版本: 2.0.4)

用户定义的错误消息, 当值大于 $max 时使用.

public string $tooBig null
$tooSmall public 属性 (可用自版本: 2.0.4)

用户定义的错误消息, 当值小于 $min 时使用.

public string $tooSmall null
$type public 属性 (可用自版本: 2.0.8)

验证器的类型.

指示是否应该验证日期, 时间或日期时间值.

此属性会影响 格式 的默认值, 并在 格式 是国际短格式之一short, medium, longfull时设置正确的行为.

这仅在安装 PHP intl 扩展 时才有效.

该属性可以设置为以下值:

  • TYPE_DATE - (default) 仅用于验证日期值, 这意味着只有不包含时间范围的值才是有效的.
  • TYPE_DATETIME - 用于验证日期时间值, 其中包含日期部分以及时间部分.
  • TYPE_TIME - 用于验证不包含日期信息的时间值.
public string $type self::TYPE_DATE

方法详情

init() public 方法

初始化对象.

在使用给定的配置初始化对象之后, 在构造函数的末尾调用此方法.

public void init ( )
parseDateValue() protected 方法

将日期字符串解析为 UNIX 时间戳.

protected integer|false parseDateValue ( $value )
$value string

表示日期的字符串.

return integer|false

UNIX 时间戳, 或失败时为false.

validateAttribute() public 方法

验证单个属性.

子类必须实现此方法才能提供实际的验证逻辑.

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

要验证的数据模型.

$attribute string

要验证的属性的名称.

validateValue() protected 方法

验证一个值.

验证器类可以实现此方法以支持数据验模型的上下文中的数据验证.

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

如果验证器不支持没有模型的数据验证.