Merge pull request #10001 from SilverFire/ip-validator-docs

Added IpValidator description to `core-validators` ru,en guides. IpValidator PHPDoc enhanced [ci skip]
2025-11-15 13:58:24 +08:00 · 2015-10-24 20:31:47 +03:00
parent 8a3babc9ef 32d1b9512c
commit e78deee92b
3 changed files with 162 additions and 18 deletions
--- a/docs/guide-ru/tutorial-core-validators.md
+++ b/docs/guide-ru/tutorial-core-validators.md
@@ -304,6 +304,78 @@ function foo($model, $attribute) {
 - `maxHeight`: максимальная высота изображения. По умолчанию null, что значит, что нет верхнего лимита.


+## [[yii\validators\IpValidator|ip]] <span id="ip"></span>
+```php
+[
+    // проверяет, что "ip_address" - это валидный IPv4 или IPv6 адрес
+    ['ip_address', 'ip'],
+
+
+    // проверяет, что "ip_address" - это валидный IPv6 адрес или подсеть,
+    // значение будет развернуто в формат полной записи IPv6 адреса
+    ['ip_address', 'ip', 'ipv4' => false, 'subnet' => null, 'expandIPv6' => true],
+
+    // проверяет, что "ip_address" - это валидный IPv4 или IPv6 адрес,
+    // разрешает использования символа отрацания `!`
+    ['ip_address', 'ip', 'negation' => true],
+]
+```
+
+Этот валидатор проверяет, является ли входящее значение валидным IPv4/IPv6 адресом или подсетью.
+Он также может изменять значение атрибута, если включена нормализация или развертывание IPv6 адресов.
+
+Валидатор имеет такие свойства:
+
+- `ipv4`: может ли проверяемое значение быть IPv4 адрессом. По умолчанию true.
+- `ipv6`: может ли проверяемое значение быть IPv6 адрессом. По умолчанию true.
+- `subnet`: может ли проверяемое значение быть IP адресом с CIDR (подсетью), например `192.168.10.0/24`
+     * `true` - указание подсети обязательно;
+     * `false` - указание подсети запрещено;
+     * `null` - указание подсети возможно, но не обязательно.
+
+    По умолчанию false.
+- `normalize`: нормализировать ли проверяемый IP адрес без CIDR к IP адресу с наименьшим CIDR
+(32 для IPv4 или 128 для IPv6). Свойство действует только если `subnet` не установлен в `false`. Например:
+    * `10.0.1.5` будет приведен к `10.0.1.5/32`
+    * `2008:db0::1` будет приведен к `2008:db0::1/128`
+- `negation`: может ли проверяемое значение иметь символ отрицания `!` в начале, например `!192.168.0.1`.
+По умолчанию false.
+- `expandIPv6`: разворачивать ли IPv6 адрес в формат полной записи.
+Например, IPv6 адрес `2008:db0::1` будет развернут в `2008:0db0:0000:0000:0000:0000:0000:0001`. По умолчанию false.
+- `ranges`: массив IPv4 или IPv6 диапазонов, которые разрешены или запрещены.
+
+    Если свойство не установлено, все IP адреса разрешены. Иначе, правила будут проверяться последовательно до первого
+вхождения. IP адрес будет запрещен, если не подпадет ни под одно правило. Например:
+    ```php
+    [
+         'client_ip', 'ip', 'ranges' => [
+             '192.168.10.128'
+             '!192.168.10.0/24',
+             'any' // разрешает все остальные IP адреса
+         ]
+    ]
+    ```
+В этом примере, доступ разрешен для всех IPv4 и IPv6 адресов кроме подсети `192.168.10.0/24`.
+IPv4 адрес `192.168.10.128` также разрешен, так как находится перед запрещающим правилом.
+- `networks`: массив псевдониимов, которые могут быть использованы в `ranges`. Формат массива:
+    * ключ - имя псевдонима
+    * значение - массив строк. Строка может быть как диапазоном адресов, так и другим псведонимом. Строка может иметь
+    символ отрицания `!` в начале (не зависит от свойства `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`
+
+> Информация: Этот валидатор стал доступным начиная с версии 2.0.7.
+
+
 ## [[yii\validators\RangeValidator|in]] <span id="in"></span>

 ```php
--- a/docs/guide/tutorial-core-validators.md
+++ b/docs/guide/tutorial-core-validators.md
@@ -367,6 +367,79 @@ validation purpose:
 - `minHeight`: the minimum height of the image. Defaults to null, meaning no lower limit.
 - `maxHeight`: the maximum height of the image. Defaults to null, meaning no upper limit.

+## [[yii\validators\IpValidator|ip]] <span id="ip"></span>
+```php
+[
+    // checks if "ip_address" is a valid IPv4 or IPv6 address
+    ['ip_address', 'ip'],
+
+    // checks if "ip_address" is a valid IPv6 address or subnet,
+    // value will be expanded to full IPv6 notation.
+    ['ip_address', 'ip', 'ipv4' => false, 'subnet' => null, 'expandIPv6' => true],
+
+    // checks if "ip_address" is a valid IPv4 or IPv6 address,
+    // allows negation character `!` at the beginning
+    ['ip_address', 'ip', 'negation' => true],
+]
+```
+
+The validator checks if the attribute value is a valid IPv4/IPv6 address or subnet.
+It also may change attribute's value if normalization or IPv6 expansion is enabled.
+
+The validator has such configuration options:
+
+- `ipv4`: whether the validating value can be an IPv4 address. Defaults to true.
+- `ipv6`: whether the validating value can be an IPv6 address. Defaults to true.
+- `subnet`: whether the address can be an IP with CIDR subnet, like `192.168.10.0/24`
+     * `true` - the subnet is required, addresses without CIDR will be rejected
+     * `false` - the address can not have the CIDR
+     * `null` - the CIDR is optional
+
+    Defaults to false.
+- `normalize`: 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.
+- `negation`: whether the validation address can have a negation character `!` at the beginning. Defaults to false.
+- `expandIPv6`: whether to expand an IPv6 address to the full notation format.
+For example, `2008:db0::1` will be expanded to `2008:0db0:0000:0000:0000:0000:0000:0001`. Defaults to false.
+- `ranges`: array of IPv4 or IPv6 ranges that are allowed or forbidden.
+
+    When the array is empty, or the option is not set, all the IP addresses are allowed.
+    Otherwise, the rules are checked sequentially until the first match is found.
+    IP address is forbidden, when it has not matched any of the rules.
+    
+    For example:
+    ```php
+    [
+         'client_ip', 'ip', '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 `192.168.10.0/24` subnet.
+IPv4 address `192.168.10.128` is also allowed, because it is listed before the restriction.
+- `networks`: array of network aliases, that can be used in `ranges`. Format of array:
+    * key - alias name
+    * value - array of strings. String can be a range, IP address or another alias. String can be
+    negated with `!` (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`
+
+> Info: This validator has been available since version 2.0.7.

 ## [[yii\validators\RangeValidator|in]] <span id="in"></span>