Class yii\validators\IpValidator

All Classes | Properties | Methods | Constants
Inheritanceyii\validators\IpValidator » yii\validators\Validator » yii\base\Component » yii\base\BaseObject
Implementsyii\base\Configurable
Available since version2.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

PropertyTypeDescriptionDefined By
$attributeNames array Attribute names. 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. 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|null 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|null 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|null Whether the address can be an IP with CIDR subnet, like `192. yii\validators\IpValidator
$validationAttributes array List of attribute names. yii\validators\Validator
$when callable|null A PHP callable whose return value determines whether this validator should be applied. yii\validators\Validator
$whenClient string|null 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

MethodDescriptionDefined 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

MethodDescriptionDefined 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

ConstantValueDescriptionDefined 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|null $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|null $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|null

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