Class yii\validators\IpValidator

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

该验证器检查属性值是否是有效的 IPv4/IPv6 地址或子网.

如果启用了 IPv6 扩展的规范化, 它还可能会更改属性的值.

以下是使用此验证器的验证规则的示例:

['ip_address', 'ip'], // IPv4 或 IPv6 地址
['ip_address', 'ip', 'ipv6' => false], // IPv4 地址(禁用 IPv6)
['ip_address', 'ip', 'subnet' => true], // 需要一个 CIDR 前缀(如 10.0.0.1/24)作为 IP 地址.
['ip_address', 'ip', 'subnet' => null], // CIDR 前缀是可选的
['ip_address', 'ip', 'subnet' => null, 'normalize' => true], // CIDR 前缀是可选的, 将在缺失时添加
['ip_address', 'ip', 'ranges' => ['192.168.0.0/24']], //  仅允许来自指定子网的 IP 地址
['ip_address', 'ip', 'ranges' => ['!192.168.0.0/24', 'any']], // 除指定子网中的 IP 外, 允许任何 IP
['ip_address', 'ip', 'expandIPv6' => true], // 将 IPv6 地址扩展为完整的符号格式

公共属性

隐藏继承的属性

属性类型描述定义在
$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
$expandIPv6 boolean 是否将 IPv6 地址扩展为完整的符号格式. yii\validators\IpValidator
$hasSubnet string 验证失败时使用的用户定义的错误消息, 因为 $subnetfalse, 但存在 CIDR 前缀. yii\validators\IpValidator
$ipv4 boolean 验证值是否可以是 IPv4 地址. yii\validators\IpValidator
$ipv4NotAllowed string 验证失败时使用的用户定义的错误消息, 因为禁用 IPv4 验证. yii\validators\IpValidator
$ipv4Pattern string 用于验证 IPv4 地址的正则表达式. yii\validators\IpValidator
$ipv6 boolean 验证值是否可以是 IPv4 地址. yii\validators\IpValidator
$ipv6NotAllowed string 验证失败时使用的用户定义的错误消息, 因为禁用 IPv6 验证. yii\validators\IpValidator
$ipv6Pattern string 用于验证 IPv6 地址的正则表达式. yii\validators\IpValidator
$isEmpty callable PHP 回调函数, 它取代 isEmpty() 的默认实现. yii\validators\Validator
$message string 验证失败时使用的用户定义的错误消息, 因为 IP 地址格式错误. yii\validators\IpValidator
$negation boolean 地址是否可以在开头有 NEGATION_CHAR 个字符. yii\validators\IpValidator
$networks array 网络别名, 可以在 $ranges 中使用. yii\validators\IpValidator
$noSubnet string 验证失败时使用的用户定义的错误消息, 因为 子网 设置为only, 但未设置 CIDR 前缀. yii\validators\IpValidator
$normalize boolean 是否将具有最小长度的 CIDR 前缀(对于 IPv4 是32, 对于 IPv6 是128)添加到没有它的地址. yii\validators\IpValidator
$notInRange string 验证失败时使用的用户定义的错误消息, 因为 $ranges 检查不允许 IP 地址. yii\validators\IpValidator
$on array|string 验证器可以应用的场景. yii\validators\Validator
$ranges array 允许或进制的 IPv4 或 IPv6 范围. 有关详细说明, 请参阅 setRanges(). > Note: 此属性的类型在getter和setter中有所不同. 有关详细信息, 请参阅 getRanges()setRanges(). yii\validators\IpValidator
$skipOnEmpty boolean 如果属性值为null或空字符串, 是否应跳过此验证规则. yii\validators\Validator
$skipOnError boolean 如果验证的属性已根据某些先前的规则已经存在某些验证错误, 是否应跳过此验证规则. yii\validators\Validator
$subnet boolean 该地址是否可以是带有 CIDR 子网的 IP, 如`192. yii\validators\IpValidator
$validationAttributes array 属性名称列表. 该属性是只读的. yii\validators\Validator
$when callable PHP 回调函数, 其返回值确定是否应该应用此验证器. yii\validators\Validator
$whenClient string 一个 JavaScript 函数名, 其返回值决定是否应在客户端应用此验证器. yii\validators\Validator
$wrongCidr string 验证失败时使用的用户定义的错误消息, 因为 CIDR 错误. yii\validators\IpValidator

公共方法

隐藏继承的方法

方法描述定义在
__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\IpValidator
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\IpValidator
getRanges() yii\validators\IpValidator
getValidationAttributes() 返回此验证器适用的属性列表. yii\validators\Validator
hasEventHandlers() 返回一个值, 指示是否有任何处理程序附加到指定的事件. yii\base\Component
hasMethod() 返回一个值, 指示方法是否已定义. yii\base\Component
hasProperty() 返回一个值, 指示属性是否已定义. yii\base\Component
init() 初始化对象. yii\validators\IpValidator
isActive() 返回一个值, 该值指示验证器对于给定场景和属性是否处于活动状态. yii\validators\Validator
isEmpty() 检查给定值是否为空. yii\validators\Validator
off() 从该组件分离现有的事件处理程序. yii\base\Component
on() 将事件处理程序附加到事件. yii\base\Component
setRanges() 设置允许或禁止的 IPv4 或 IPv6 范围. yii\validators\IpValidator
trigger() 触发事件. yii\base\Component
validate() 验证给定的值. yii\validators\Validator
validateAttribute() 验证单个属性. yii\validators\IpValidator
validateAttributes() 验证指定的对象. yii\validators\Validator

受保护的方法

隐藏继承的方法

方法描述定义在
formatMessage() 使用 I18N 格式化消息, 或者当\Yii::$app不可用时使用简单的strtr函数. yii\validators\Validator
validateIPv4() 验证 IPv4 地址. yii\validators\IpValidator
validateIPv6() 验证 IPv6 地址. yii\validators\IpValidator
validateValue() 验证一个值. yii\validators\IpValidator

常量

隐藏继承的常量

常量描述定义在
NEGATION_CHAR '!' 否定字符. 当 $negation 设置为true时, 用于否定 $ranges$networks 或否定验证值. yii\validators\IpValidator

属性详情

$expandIPv6 public 属性

是否将 IPv6 地址扩展为完整的符号格式. 默认为false.

public boolean $expandIPv6 false
$hasSubnet public 属性

验证失败时使用的用户定义的错误消息, 因为 $subnetfalse, 但存在 CIDR 前缀.

你可以在消息中使用以下占位符:

  • {attribute}: 要验证的属性的标签.
  • {value}: 要验证的属性的值.

参见 $subnet.

public string $hasSubnet null
$ipv4 public 属性

验证值是否可以是 IPv4 地址. 默认为true.

public boolean $ipv4 true
$ipv4NotAllowed public 属性

验证失败时使用的用户定义的错误消息, 因为禁用 IPv4 验证.

你可以在消息中使用以下占位符:

  • {attribute}: 要验证的属性的标签.
  • {value}: 要验证的属性的值.

参见 $ipv4.

public string $ipv4NotAllowed null
$ipv4Pattern public 属性

用于验证 IPv4 地址的正则表达式.

public string $ipv4Pattern '/^(?:(?:2(?:[0-4][0-9]|5[0-5])|[0-1]?[0-9]?[0-9])\.){3}(?:(?:2([0-4][0-9]|5[0-5])|[0-1]?[0-9]?[0-9]))$/'
$ipv6 public 属性

验证值是否可以是 IPv4 地址. 默认为true.

public boolean $ipv6 true
$ipv6NotAllowed public 属性

验证失败时使用的用户定义的错误消息, 因为禁用 IPv6 验证.

你可以在消息中使用以下占位符:

  • {attribute}: 要验证的属性的标签.
  • {value}: 要验证的属性的值.

参见 $ipv6.

public string $ipv6NotAllowed null
$ipv6Pattern public 属性

用于验证 IPv6 地址的正则表达式.

public string $ipv6Pattern '/^(([0-9a-fA-F]{1,4}:){7,7}[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,7}:|([0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,5}(:[0-9a-fA-F]{1,4}){1,2}|([0-9a-fA-F]{1,4}:){1,4}(:[0-9a-fA-F]{1,4}){1,3}|([0-9a-fA-F]{1,4}:){1,3}(:[0-9a-fA-F]{1,4}){1,4}|([0-9a-fA-F]{1,4}:){1,2}(:[0-9a-fA-F]{1,4}){1,5}|[0-9a-fA-F]{1,4}:((:[0-9a-fA-F]{1,4}){1,6})|:((:[0-9a-fA-F]{1,4}){1,7}|:)|fe80:(:[0-9a-fA-F]{0,4}){0,4}%[0-9a-zA-Z]{1,}|::(ffff(:0{1,4}){0,1}:){0,1}((25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])\.){3,3}(25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])|([0-9a-fA-F]{1,4}:){1,4}:((25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])\.){3,3}(25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9]))$/'
$message public 属性

验证失败时使用的用户定义的错误消息, 因为 IP 地址格式错误.

你可以在消息中使用以下占位符:

  • {attribute}: 要验证的属性的标签.
  • {value}: 要验证的属性的值.
public string $message null
$negation public 属性

地址是否可以在开头有 NEGATION_CHAR 个字符. 默认为false.

public boolean $negation false
$networks public 属性

网络别名, 可以在 $ranges 中使用.

  • key - 别名
  • value - 字符串数组, 字符串可以是 IP 范围, IP 地址或其它别名. 字符串可以用 NEGATION_CHAR (与negation选项无关)取反.

默认情况下定义以下别名:

  • *: any
  • any: 0.0.0.0/0, ::/0
  • private: 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, fd00::/8
  • multicast: 224.0.0.0/4, ff00::/8
  • linklocal: 169.254.0.0/16, fe80::/10
  • localhost: 127.0.0.0/8', ::1
  • documentation: 192.0.2.0/24, 198.51.100.0/24, 203.0.113.0/24, 2001:db8::/32
  • system: multicast, linklocal, localhost, documentation
public array $networks = ['*' => ['any'], 'any' => ['0.0.0.0/0''::/0'], 'private' => ['10.0.0.0/8''172.16.0.0/12''192.168.0.0/16''fd00::/8'], 'multicast' => ['224.0.0.0/4''ff00::/8'], 'linklocal' => ['169.254.0.0/16''fe80::/10'], 'localhost' => ['127.0.0.0/8''::1'], 'documentation' => ['192.0.2.0/24''198.51.100.0/24''203.0.113.0/24''2001:db8::/32'], 'system' => ['multicast''linklocal''localhost''documentation']]
$noSubnet public 属性

验证失败时使用的用户定义的错误消息, 因为 子网 设置为only, 但未设置 CIDR 前缀.

你可以在消息中使用以下占位符:

  • {attribute}: 要验证的属性的标签.
  • {value}: 要验证的属性的值.

参见 $subnet.

public string $noSubnet null
$normalize public 属性

是否将具有最小长度的 CIDR 前缀(对于 IPv4 是32, 对于 IPv6 是128)添加到没有它的地址. 默认为false.

仅当subnet不是false时才有效. 例如:

  • 10.0.1.5 将标准化为 10.0.1.5/32
  • 2008:db0::1 将标准化为 2008:db0::1/128

参见 $subnet.

public boolean $normalize false
$notInRange public 属性

验证失败时使用的用户定义的错误消息, 因为 $ranges 检查不允许 IP 地址.

你可以在消息中使用以下占位符:

  • {attribute}: 要验证的属性的标签.
  • {value}: 要验证的属性的值.

参见 $ranges.

public string $notInRange null
$ranges public 属性

允许或进制的 IPv4 或 IPv6 范围. 有关详细说明, 请参阅 setRanges(). > Note: 此属性的类型在getter和setter中有所不同. 有关详细信息, 请参阅 getRanges()setRanges().

public array $ranges null
$subnet public 属性

该地址是否可以是带有 CIDR 子网的 IP, 如192.168.10.0/24.

以下值是可能的:

  • false - 该地址不能有子网(default).
  • true - 必须指定子网.
  • null - 指定子网是可选的.
public boolean $subnet false
$wrongCidr public 属性

验证失败时使用的用户定义的错误消息, 因为 CIDR 错误.

你可以在消息中使用以下占位符:

  • {attribute}: 要验证的属性的标签.
  • {value}: 要验证的属性的值.

参见 $subnet.

public string $wrongCidr null

方法详情

clientValidateAttribute() public 方法

返回执行客户端验证所需的 JavaScript.

调用 getClientOptions() 为客户端验证生成选项数组.

如果验证器可以支持客户端验证, 则可以重写此方法以返回 JavaScript 验证代码.

以下 JavaScript 变量是预定义的, 可以在验证代码中使用:

  • attribute: 描述正在验证的属性的对象;
  • value: 正在验证的值;
  • messages: 用于保存属性的验证错误消息的数组;
  • deferred: 用于保存延迟对象以进行异步验证的数组;
  • $form: 包含表单元素的 jQuery 对象.

attribute对象包含以下属性:

  • id: 在表单中标识该属性的唯一 ID(eg. loginform-username);
  • name: 属性名称或表达式(eg. [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() public 方法 (可用自版本: 2.0.11)

返回客户端验证选项.

此方法通常从 clientValidateAttribute() 中调用. 你可以重写此方法来修改将传递给客户端验证的选项.

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

正在验证的模型.

$attribute string

正在验证的属性名称.

return array

客户端验证选项.

getRanges() public 方法

public array getRanges ( )
return array

允许或禁止的 IPv4 或 IPv6 范围.

init() public 方法

初始化对象.

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

public void init ( )
setRanges() public 方法

设置允许或禁止的 IPv4 或 IPv6 范围.

执行以下准备任务:

  • 递归的用它们的值替换别名(在 $networks 中描述).
  • 删除重复项.
public void setRanges ( $ranges )
$ranges array|string

允许或禁止的 IPv4 或 IPv6 范围.

当数组为空或未设置选项时, 允许所有 IP 地址.

否则, 将按顺序检查规则, 直到找到第一个匹配. 如果 IP 地址未匹配任何规则, 则禁止该 IP 地址.

例如:

[
     'ranges' => [
         '192.168.10.128'
         '!192.168.10.0/24',
         'any' // 允许任何其它 IP 地址
     ]
]

在此示例中, 除了192.168.10.0/24子网之外, 所有的 IPv4 和 IPv6 地址都被允许访问. IPv4 地址192.168.10.128也是允许的, 因为它在限制之前被列出.

validateAttribute() public 方法

验证单个属性.

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

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

要验证的数据模型.

$attribute string

要验证的属性的名称.

validateIPv4() protected 方法

验证 IPv4 地址.

protected boolean validateIPv4 ( $value )
$value string
validateIPv6() protected 方法

验证 IPv6 地址.

protected boolean validateIPv6 ( $value )
$value 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

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