# Class yii\validators\IpValidator

Inheritance | yii\validators\IpValidator » yii\validators\Validator » yii\base\Component » yii\base\BaseObject
Implements | yii\base\Configurable
Available since version | 2.0.7
Source Code | https://github.com/yiisoft/yii2/blob/master/framework/validators/IpValidator.php

The validator checks if the attribute value is a valid IPv4/IPv6 address or subnet.

It also may change attribute's value if normalization of IPv6 expansion is enabled.

The following are examples of validation rules using this validator:

    ['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

## Public Properties

Hide inherited properties

Property | Type | Description | Defined By
--- | --- | --- | ---
$attributeNames | array | Attribute names. This property is read-only. | yii\validators\Validator
$attributes | array|string | Attributes to be validated by this validator. | yii\validators\Validator
$behaviors | yii\base\Behavior[] | List of behaviors attached to this component. This property is read-only. | yii\base\Component
$builtInValidators | array | List of built-in validators (name => class or configuration) | yii\validators\Validator
$enableClientValidation | boolean | Whether to enable client-side validation for this validator. | yii\validators\Validator
$except | array|string | Scenarios that the validator should not be applied to. | yii\validators\Validator
$expandIPv6 | boolean | Whether to expand an IPv6 address to the full notation format. | yii\validators\IpValidator
$hasSubnet | string | User-defined error message is used when validation fails due to $subnet is false, but CIDR prefix is present. | yii\validators\IpValidator
$ipv4 | boolean | Whether the validating value can be an IPv4 address. | yii\validators\IpValidator
$ipv4NotAllowed | string | User-defined error message is used when validation fails due to the disabled IPv4 validation. | yii\validators\IpValidator
$ipv4Pattern | string | Regexp-pattern to validate IPv4 address | yii\validators\IpValidator
$ipv6 | boolean | Whether the validating value can be an IPv6 address. | yii\validators\IpValidator
$ipv6NotAllowed | string | User-defined error message is used when validation fails due to the disabled IPv6 validation. | yii\validators\IpValidator
$ipv6Pattern | string | Regexp-pattern to validate IPv6 address | yii\validators\IpValidator
$isEmpty | callable | A PHP callable that replaces the default implementation of isEmpty(). | yii\validators\Validator
$message | string | User-defined error message is used when validation fails due to the wrong IP address format. | yii\validators\IpValidator
$negation | boolean | Whether address may have a NEGATION_CHAR character at the beginning. | yii\validators\IpValidator
$networks | array | The network aliases, that can be used in $ranges. | yii\validators\IpValidator
$noSubnet | string | User-defined error message is used when validation fails due to subnet $subnet set to 'only', but the CIDR prefix is not set. | yii\validators\IpValidator
$normalize | boolean | Whether to add the CIDR prefix with the smallest length (32 for IPv4 and 128 for IPv6) to an address without it. | yii\validators\IpValidator
$notInRange | string | User-defined error message is used when validation fails due to IP address is not not allowed by $ranges check. | yii\validators\IpValidator
$on | array|string | Scenarios that the validator can be applied to. | yii\validators\Validator
$ranges | array | The IPv4 or IPv6 ranges that are allowed or forbidden. See setRanges() for detailed description. Note that the type of this property differs in getter and setter. See getRanges() and setRanges() for details. | yii\validators\IpValidator
$skipOnEmpty | boolean | Whether this validation rule should be skipped if the attribute value is null or an empty string. | yii\validators\Validator
$skipOnError | boolean | Whether this validation rule should be skipped if the attribute being validated already has some validation error according to some previous rules. | yii\validators\Validator
$subnet | boolean | Whether the address can be an IP with CIDR subnet, like `192. | yii\validators\IpValidator
$validationAttributes | array | List of attribute names. This property is read-only. | yii\validators\Validator
$when | callable | A PHP callable whose return value determines whether this validator should be applied. | yii\validators\Validator
$whenClient | string | A JavaScript function name whose return value determines whether this validator should be applied on the client-side. | yii\validators\Validator
$wrongCidr | string | User-defined error message is used when validation fails due to the wrong CIDR. | yii\validators\IpValidator

## Public Methods

Hide inherited methods

Method | Description | Defined By
--- | --- | ---
__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() | Adds an error about the specified attribute to the model object. | 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() | Returns the JavaScript needed for performing client-side validation. | yii\validators\IpValidator
createValidator() | Creates a validator object. | 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() | Returns cleaned attribute names without the `!` character at the beginning. | yii\validators\Validator
getBehavior() | Returns the named behavior object. | yii\base\Component
getBehaviors() | Returns all behaviors attached to this component. | yii\base\Component
getClientOptions() | Returns the client-side validation options. | yii\validators\IpValidator
getRanges() |  | yii\validators\IpValidator
getValidationAttributes() | Returns a list of attributes this validator applies to. | 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() | Returns a value indicating whether the validator is active for the given scenario and attribute. | yii\validators\Validator
isEmpty() | Checks if the given value is empty. | 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() | Set the IPv4 or IPv6 ranges that are allowed or forbidden. | yii\validators\IpValidator
trigger() | Triggers an event. | yii\base\Component
validate() | Validates a given value. | yii\validators\Validator
validateAttribute() | Validates a single attribute. | yii\validators\IpValidator
validateAttributes() | Validates the specified object. | yii\validators\Validator

## Protected Methods

Hide inherited methods

Method | Description | Defined By
--- | --- | ---
formatMessage() | Formats a mesage using the I18N, or simple strtr if `\Yii::$app` is not available. | yii\validators\Validator
validateIPv4() | Validates IPv4 address. | yii\validators\IpValidator
validateIPv6() | Validates IPv6 address. | yii\validators\IpValidator
validateValue() | Validates a value. | yii\validators\IpValidator

## Constants

Hide inherited constants

Constant | Value | Description | Defined By
--- | --- | --- | ---
NEGATION_CHAR | '!' | Negation char. Used to negate $ranges or $networks or to negate validating value when $negation is set to `true`. | yii\validators\IpValidator

## Property Details

$expandIPv6 public property

Whether to expand an IPv6 address to the full notation format. Defaults to `false`.

public boolean $expandIPv6 = false
$hasSubnet public property

User-defined error message is used when validation fails due to $subnet is false, but CIDR prefix is present.

You may use the following placeholders in the message:

- `{attribute}`: the label of the attribute being validated
- `{value}`: the value of the attribute being validated

See also $subnet.

public string $hasSubnet = null
$ipv4 public property

Whether the validating value can be an IPv4 address. Defaults to `true`.

public boolean $ipv4 = true
$ipv4NotAllowed public property

User-defined error message is used when validation fails due to the disabled IPv4 validation.

You may use the following placeholders in the message:

- `{attribute}`: the label of the attribute being validated
- `{value}`: the value of the attribute being validated

See also $ipv4.

public string $ipv4NotAllowed = null
$ipv4Pattern public property

Regexp-pattern to validate IPv4 address

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 property

Whether the validating value can be an IPv6 address. Defaults to `true`.

public boolean $ipv6 = true
$ipv6NotAllowed public property

User-defined error message is used when validation fails due to the disabled IPv6 validation.

You may use the following placeholders in the message:

- `{attribute}`: the label of the attribute being validated
- `{value}`: the value of the attribute being validated

See also $ipv6.

public string $ipv6NotAllowed = null
$ipv6Pattern public property

Regexp-pattern to validate IPv6 address

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 property

User-defined error message is used when validation fails due to the wrong IP address format.

You may use the following placeholders in the message:

- `{attribute}`: the label of the attribute being validated
- `{value}`: the value of the attribute being validated

public string $message = null
$negation public property

Whether address may have a NEGATION_CHAR character at the beginning. Defaults to `false`.

public boolean $negation = false
$networks public property

The network aliases, that can be used in $ranges.

- key - alias name
- value - array of strings. String can be an IP range, IP address or another alias. String can be negated with NEGATION_CHAR (independent of `negation` option).

The following aliases are defined by default:

- `*`: `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 property

User-defined error message is used when validation fails due to subnet $subnet set to 'only', but the CIDR prefix is not set.

You may use the following placeholders in the message:

- `{attribute}`: the label of the attribute being validated
- `{value}`: the value of the attribute being validated

See also $subnet.

public string $noSubnet = null
$normalize public property

Whether to add the CIDR prefix with the smallest length (32 for IPv4 and 128 for IPv6) to an address without it. Works only when `subnet` is not `false`. For example:

- `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`.

See also $subnet.

public boolean $normalize = false
$notInRange public property

User-defined error message is used when validation fails due to IP address is not not allowed by $ranges check.

You may use the following placeholders in the message:

- `{attribute}`: the label of the attribute being validated
- `{value}`: the value of the attribute being validated

See also $ranges.

public string $notInRange = null
$ranges public property

The IPv4 or IPv6 ranges that are allowed or forbidden. See setRanges() for detailed description. Note that the type of this property differs in getter and setter. See getRanges() and setRanges() for details.

public array $ranges = null
$subnet public property

Whether the address can be an IP with CIDR subnet, like `192.168.10.0/24`. The following values are possible:

- `false` - the address must not have a subnet (default).
- `true` - specifying a subnet is required.
- `null` - specifying a subnet is optional.

public boolean $subnet = false
$wrongCidr public property

User-defined error message is used when validation fails due to the wrong CIDR.

You may use the following placeholders in the message:

- `{attribute}`: the label of the attribute being validated
- `{value}`: the value of the attribute being validated

See also $subnet.

public string $wrongCidr = null

## Method Details

clientValidateAttribute() public method

Returns the JavaScript needed for performing client-side validation.

Calls getClientOptions() to generate options array for client-side validation.

You may override this method to return the JavaScript validation code if the validator can support client-side validation.

The following JavaScript variables are predefined and can be used in the validation code:

- `attribute`: an object describing the the attribute being validated.
- `value`: the value being validated.
- `messages`: an array used to hold the validation error messages for the attribute.
- `deferred`: an array used to hold deferred objects for asynchronous validation
- `$form`: a jQuery object containing the form element

The `attribute` object contains the following properties:

- `id`: a unique ID identifying the attribute (e.g. "loginform-username") in the form
- `name`: attribute name or expression (e.g. "[0]content" for tabular input)
- `container`: the jQuery selector of the container of the input field
- `input`: the jQuery selector of the input field under the context of the form
- `error`: the jQuery selector of the error tag under the context of the container
- `status`: status of the input field, 0: empty, not entered before, 1: validated, 2: pending validation, 3: validating

public string|null clientValidateAttribute ( $model, $attribute, $view )
$model | yii\base\Model | The data model being validated
$attribute | string | The name of the attribute to be validated.
$view | yii\web\View | The view object that is going to be used to render views or view files containing a model form with this validator applied.
return | string|null | The client-side validation script. Null if the validator does not support client-side validation.

getClientOptions() public method (available since version 2.0.11)

Returns the client-side validation options.

This method is usually called from clientValidateAttribute(). You may override this method to modify options that will be passed to the client-side validation.

public array getClientOptions ( $model, $attribute )
$model | yii\base\Model | The model being validated
$attribute | string | The attribute name being validated
return | array | The client-side validation options

getRanges() public method

public array getRanges ( )
return | array | The IPv4 or IPv6 ranges that are allowed or forbidden.

init() public method

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

Set the IPv4 or IPv6 ranges that are allowed or forbidden.

The following preparation tasks are performed:

- Recursively substitutes aliases (described in $networks) with their values.
- Removes duplicates

public void setRanges ( $ranges )

$ranges

array|string

The IPv4 or IPv6 ranges that are allowed or forbidden.

When the array is empty, or the option not set, all IP addresses are allowed.

Otherwise, the rules are checked sequentially until the first match is found. An IP address is forbidden, when it has not matched any of the rules.

Example:

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

In this example, access is allowed for all the IPv4 and IPv6 addresses excluding the `192.168.10.0/24` subnet. IPv4 address `192.168.10.128` is also allowed, because it is listed before the restriction.

validateAttribute() public method

Validates a single attribute.

Child classes must implement this method to provide the actual validation logic.

public void validateAttribute ( $model, $attribute )
$model | yii\base\Model | The data model to be validated
$attribute | string | The name of the attribute to be validated.

validateIPv4() protected method

Validates IPv4 address.

protected boolean validateIPv4 ( $value )
$value | string |

validateIPv6() protected method

Validates IPv6 address.

protected boolean validateIPv6 ( $value )
$value | string |

validateValue() protected method

Validates a value.

A validator class can implement this method to support data validation out of the context of a data model.

protected array|null validateValue ( $value )
$value | mixed | The data value to be validated.

return

array|null

The error message and the array of parameters to be inserted into the error message. ```php if (!$valid) {

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

}

return null; ``` for this example `message` template can contain `{param1}`, `{formattedLimit}`, `{mimeTypes}`, `{param4}`

Null should be returned if the data is valid.

throws | yii\base\NotSupportedException | if the validator does not supporting data validation without a model