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
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
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
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
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
Whether to expand an IPv6 address to the full notation format.
Defaults to false
.
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.
Whether the validating value can be an IPv4 address. Defaults to true
.
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.
Regexp-pattern to validate IPv4 address
Whether the validating value can be an IPv6 address. Defaults to true
.
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.
Regexp-pattern to validate IPv6 address
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
Whether address may have a NEGATION_CHAR character at the beginning.
Defaults to false
.
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
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.
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 to10.0.1.5/32
2008:db0::1
will be normalized to2008:db0::1/128
Defaults tofalse
.
See also $subnet.
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.
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.
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.
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.
Method Details
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 formname
: attribute name or expression (e.g. "[0]content" for tabular input)container
: the jQuery selector of the container of the input fieldinput
: the jQuery selector of the input field under the context of the formerror
: the jQuery selector of the error tag under the context of the containerstatus
: 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. |
---|
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 |
---|
public array getRanges ( ) | ||
return | array | The IPv4 or IPv6 ranges that are allowed or forbidden. |
---|
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 ( ) |
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:
In this example, access is allowed for all the IPv4 and IPv6 addresses excluding the |
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. |
Validates IPv4 address.
protected boolean validateIPv4 ( $value ) | ||
$value | string |
Validates IPv6 address.
protected boolean validateIPv6 ( $value ) | ||
$value | string |
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.
} return null;
Null should be returned if the data is valid. |
---|---|---|
throws | yii\base\NotSupportedException | if the validator does not supporting data validation without a model |
Signup or Login in order to comment.