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/yiichina/yii2/blob/api/framework/validators/IpValidator.php

这个校验器校验属性值是否是一个合法的 IPv4/IPv6 地址或者子网。

如果启用 IPv6 扩展标准化，它同样会改变属性值。

如下是使用这个校验器的校验规则示例：

['ip_address', 'ip'], // IPv4 or IPv6 address
['ip_address', 'ip', 'ipv6' => false], // IPv4 address (IPv6 is disabled)
['ip_address', 'ip', 'subnet' => true], // requires a CIDR prefix (like 10.0.0.1/24) for the IP address
['ip_address', 'ip', 'subnet' => null], // CIDR prefix is optional
['ip_address', 'ip', 'subnet' => null, 'normalize' => true], // CIDR prefix is optional and will be added when missing
['ip_address', 'ip', 'ranges' => ['192.168.0.0/24']], // only IP addresses from the specified subnet are allowed
['ip_address', 'ip', 'ranges' => ['!192.168.0.0/24', 'any']], // any IP is allowed except IP in the specified subnet
['ip_address', 'ip', 'expandIPv6' => true], // expands IPv6 address to a full notation format

公共属性

隐藏继承的属性

属性	类型	描述	被定义在
$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
$enableClientValidation	boolean	是否启用这个校验器的客户端校验。实际的校验过程是通过 clientValidateAttribute() 返回的 JS 代码来执行。如果这个方法返回 null，即使这个属性值为 true ，也不会执行任何客户端校验。	yii\validators\Validator
$except	array\|string	校验器不应该应用的情景。对于多情景，请以一个数组的形式指定它们。对于单情景，你可以使用一个字符串或者一个数组。	yii\validators\Validator
$expandIPv6	boolean	是否将 IPv6 扩展为完整格式。默认为 `false`。	yii\validators\IpValidator
$hasSubnet	string	用户自定义错误消息，当 $subnet 为 false 时，但提供了 CIDR 后缀导致校验失败。你可以在消息中使用如下的占位符： - `{attribute}`: 被校验的属性标签 - `{value}`: 被校验的属性值	yii\validators\IpValidator
$ipv4	boolean	待校验的值是否可以是 IPv4 地址。默认为 `true`。	yii\validators\IpValidator
$ipv4NotAllowed	string	用户自定义错误消息用于禁用 IPv4 校验时遇到 IPv4 地址。你可以在消息中使用如下的占位符： - `{attribute}`: 被校验的属性标签 - `{value}`: 被校验的属性值	yii\validators\IpValidator
$ipv4Pattern	string	用于校验 IPv4 地址的正则表达式	yii\validators\IpValidator
$ipv6	boolean	待校验的值是否可以是 IPv6 地址。默认为 `true`。	yii\validators\IpValidator
$ipv6NotAllowed	string	用户自定义错误消息用于禁用 IPv6 校验时遇到 IPv6 地址。你可以在消息中使用如下的占位符： - `{attribute}`: 被校验的属性标签 - `{value}`: 被校验的属性值	yii\validators\IpValidator
$ipv6Pattern	string	用于校验 IPv6 地址的正则表达式	yii\validators\IpValidator
$isEmpty	callable	用于替换默认的 isEmpty() 空值校验方法，如果没有设置，将会使用 isEmpty() 做空值校验。这个函数的声明应该为 `function ($value)`，它的返回值为一个代表这个值是否为空的布尔值。	yii\validators\Validator
$message	string	用户自定义错误消息用于校验遇到错误的 IP 地址格式时。你可以在消息中使用如下的占位符： - `{attribute}`: 被校验的属性标签 - `{value}`: 被校验的属性值	yii\validators\IpValidator
$negation	boolean	地址是否可以包含 NEGATION_CHAR 在开头处。默认为 `false`。	yii\validators\IpValidator
$networks	array	网络别名，这个可以被用于 $ranges 中。 - key - 别名名称 - value - 数组字符串。字符串可以是 IP 范围，IP 地址或者其他别名。字符串可以用 NEGATION_CHAR 取反（和 `negation` 属性独立）以下是预定义的别名： - `*`: `any` - `any`: `0.	yii\validators\IpValidator
$noSubnet	string	用户自定义错误消息当 $subnet 设置为 'only'，但是 CIDR 后缀没有设置时，校验失败。你可以在消息中使用如下的占位符： - `{attribute}`: 被校验的属性标签 - `{value}`: 被校验的属性值	yii\validators\IpValidator
$normalize	boolean	当地址没有后缀时，是否默认添加最小长度的 CIDR 后缀（ IPv4 为32，IPv6 为128）。只有 `subnet` 不为 `false` 时才有效。例如： - `10.	yii\validators\IpValidator
$notInRange	string	用户自定义错误消息，当 IP 地址不在 $ranges 允许的范围。你可以在消息中使用如下的占位符： - `{attribute}`: 被校验的属性标签 - `{value}`: 被校验的属性值	yii\validators\IpValidator
$on	array\|string	校验器被应用的情景。对于多情景，请以一个数组的形式指定它们。对于单情景，你可以使用一个字符串或者一个数组。	yii\validators\Validator
$ranges	array	允许或者禁止的 IPv4 或者 IPv6 范围.	yii\validators\IpValidator
$skipOnEmpty	boolean	当被校验的属性值为 null 或者空字符串时，是否该跳过这个校验规则。	yii\validators\Validator
$skipOnError	boolean	当被校验的属性根据之前的校验规则已经有一些校验错误时，这个校验规则是否应该被跳过。默认为 true。	yii\validators\Validator
$subnet	boolean	地址是否可以为一个包含 CIDR 子网的 IP，例如 `192.	yii\validators\IpValidator
$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
$wrongCidr	string	用户自定义错误消息用于因 CIDR 产生时。你可以在消息中使用如下的占位符： - `{attribute}`: 被校验的属性标签 - `{value}`: 被校验的属性值	yii\validators\IpValidator

公共方法

隐藏继承的方法

方法	描述	被定义在
__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\IpValidator
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\IpValidator
getRanges()		yii\validators\IpValidator
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\IpValidator
isActive()	返回一个值代表当前校验器在当前情景和属性下是否是激活状态。	yii\validators\Validator
isEmpty()	检测指定的值是否为空。如果它是一个 null，一个空的数组，或者一个空字符串，那么它会被认为是一个空值。注意这个方法和 PHP 的 empty() 函数不同，当值为 0 时，它会返还 false 。（非空值）	yii\validators\Validator
off()	Detaches an existing event handler from this component.	yii\base\Component
on()	Attaches an event handler to an event.	yii\base\Component
setRanges()	设置允许或者禁止的 IPv4 或者 IPv6 范围。	yii\validators\IpValidator
trigger()	Triggers an event.	yii\base\Component
validate()	校验一个指定的值。你可以使用这个方法在数据模型上下文之外的地方校验一个值。	yii\validators\Validator
validateAttribute()	校验单个属性。子类必须实现这个方法以实现具体的校验逻辑。	yii\validators\IpValidator
validateAttributes()	校验指定的对象。	yii\validators\Validator

受保护的方法

隐藏继承的方法

方法	描述	被定义在
formatMessage()	使用 I18N 格式化消息，或者只是简单的 strtr ，如果 `\Yii::$app` 不可用的话。	yii\validators\Validator
validateIPv4()	校验 IPv4 地址。	yii\validators\IpValidator
validateIPv6()	校验 IPv6 地址。	yii\validators\IpValidator
validateValue()	校验一个值。一个校验类可以实现这个方法，以支持在数据模型上下文之外的地方支持数据校验。	yii\validators\IpValidator

常量

隐藏继承的常量

常量	值	描述	被定义在
NEGATION_CHAR	'!'	否定操作符。用于否定 $ranges 或者 $networks 或者当 $negation 设置为 `true` 时，否定校验的值。	yii\validators\IpValidator

属性详情

$expandIPv6 公共属性

是否将 IPv6 扩展为完整格式。默认为 false。

public boolean $expandIPv6 = false

$hasSubnet 公共属性

用户自定义错误消息，当 $subnet 为 false 时，但提供了 CIDR 后缀导致校验失败。

你可以在消息中使用如下的占位符：

{attribute}: 被校验的属性标签
{value}: 被校验的属性值

参见 $subnet.

public string $hasSubnet = null

$ipv4 公共属性

待校验的值是否可以是 IPv4 地址。默认为 true。

public boolean $ipv4 = true

$ipv4NotAllowed 公共属性

用户自定义错误消息用于禁用 IPv4 校验时遇到 IPv4 地址。

你可以在消息中使用如下的占位符：

{attribute}: 被校验的属性标签
{value}: 被校验的属性值

参见 $ipv4.

public string $ipv4NotAllowed = null

$ipv4Pattern 公共属性

用于校验 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 公共属性

待校验的值是否可以是 IPv6 地址。默认为 true。

public boolean $ipv6 = true

$ipv6NotAllowed 公共属性

用户自定义错误消息用于禁用 IPv6 校验时遇到 IPv6 地址。

你可以在消息中使用如下的占位符：

{attribute}: 被校验的属性标签
{value}: 被校验的属性值

参见 $ipv6.

public string $ipv6NotAllowed = null

$ipv6Pattern 公共属性

用于校验 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 公共属性

用户自定义错误消息用于校验遇到错误的 IP 地址格式时。

你可以在消息中使用如下的占位符：

{attribute}: 被校验的属性标签
{value}: 被校验的属性值

public string $message = null

$negation 公共属性

地址是否可以包含 NEGATION_CHAR 在开头处。默认为 false。

public boolean $negation = false

$networks 公共属性

网络别名，这个可以被用于 $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 公共属性

用户自定义错误消息当 $subnet 设置为 'only'，但是 CIDR 后缀没有设置时，校验失败。

你可以在消息中使用如下的占位符：

{attribute}: 被校验的属性标签
{value}: 被校验的属性值

参见 $subnet.

public string $noSubnet = null

$normalize 公共属性

当地址没有后缀时，是否默认添加最小长度的 CIDR 后缀（ IPv4 为32，IPv6 为128）。只有 subnet 不为 false 时才有效。例如：

10.0.1.5 will normalized to 10.0.1.5/32
2008:db0::1 will be normalized to 2008:db0::1/128 Defaults to false.

参见 $subnet.

public boolean $normalize = false

$notInRange 公共属性

用户自定义错误消息，当 IP 地址不在 $ranges 允许的范围。

你可以在消息中使用如下的占位符：

{attribute}: 被校验的属性标签
{value}: 被校验的属性值

参见 $ranges.

public string $notInRange = null

$ranges 公共属性

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

如果数组是空的，或者属性未涉足，所以的 IP 地址将被允许。

其他情况，这些规则将被依次执行直到找到第一条匹配的。当一个 IP 地址没有被任意规则匹配时，它将被禁止。

例如:

[
     'ranges' => [
         '192.168.10.128'
         '!192.168.10.0/24',
         'any' // allows any other IP addresses
     ]
]

在这个例子中，所有的 IPv4 和 IPv6 地址都被允许，除了子网 192.168.10.0/24。 IPv4 地址 192.168.10.128 将被允许，因为它列在限制前面。

public array getRanges ( )
public void setRanges ( $ranges )

$subnet 公共属性

地址是否可以为一个包含 CIDR 子网的 IP，例如 192.168.10.0/24。可能是以下的值之一：

false - 地址不能包含子网（默认）。
true - 地址必须包含子网。
null - 地址不必须包含子网。

public boolean $subnet = false

$wrongCidr 公共属性

用户自定义错误消息用于因 CIDR 产生时。

你可以在消息中使用如下的占位符：

{attribute}: 被校验的属性标签
{value}: 被校验的属性值

参见 $subnet.

public string $wrongCidr = 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	客户端校验参数。

getRanges() 公共方法

public array getRanges()
return	array	允许或者禁止的 IPv4 或者 IPv6 地址

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()

setRanges() 公共方法

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

会执行以下预处理过程：

递归的将别名用其值替换（在 $networks 中定义）
移除重复值

public void setRanges($ranges)
$ranges	array	允许或者禁止的 IPv4 或者 IPv6 范围. 如果数组是空的，或者属性未涉足，所以的 IP 地址将被允许。其他情况，这些规则将被依次执行直到找到第一条匹配的。当一个 IP 地址没有被任意规则匹配时，它将被禁止。例如: `[ 'ranges' => [ '192.168.10.128' '!192.168.10.0/24', 'any' // allows any other IP addresses ] ]` 在这个例子中，所有的 IPv4 和 IPv6 地址都被允许，除了子网 `192.168.10.0/24`。 IPv4 地址 `192.168.10.128` 将被允许，因为它列在限制前面。

validateAttribute() 公共方法

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

public void validateAttribute($model, $attribute)
$model	yii\base\Model	被校验的数据模型对象。
$attribute	string	被校验的属性名称。

validateIPv4() 受保护方法

校验 IPv4 地址。

protected boolean validateIPv4($value)
$value	string

validateIPv6() 受保护方法

校验 IPv6 地址。

protected boolean validateIPv6($value)
$value	string

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	如果校验器不支持模型外数据校验。