Ip - APIPHP开源框架

>i 本文档的最新修订日期是： > **2023-05-27** # Ip :: 通过对IP地址（ `IPv4` ）黑白名单的操作，来允许或阻止程序运行。如要使用本模块，请务必保证temp目录下的ip-blacklist.php和ip-whitelist.php具有 `读写权限` ，否则将报错。当上述两个文件不存在时，将 `自动建立` 这两个文件。 >d 请勿手动修改这两个文件！ # 公共参数 * **`type（类型）`** `(String)` `默认值见方法参数`：用以指定需要操作的名单的类型。当值为 `b` 时，将对 `黑名单` 进行操作；当值为 `w` 时，将对 `白名单` 进行操作。 * **`ip_start（起始ip）`** `(String)` `默认值见方法参数`：用以指定添加的 `确切IP地址` ，或一个IP地址段的 `起始IP地址` 。IP地址或IP地址段的起始地址中允许通配符“ `*` ”。 **如果仅传入了 `ip_start` 参数，而不传入 `ip_end` 参数：** 1. 想要在记录中添加一个 `确切的IP地址` ，例如192.168.15.3，请传入字符串 `192.168.15.3` ； 2. 想要添加一个 `前缀相同` 的IP段，比如192.168 `.0.0` 至192.168 `.255.255` ，请传入字符串 `192.168.*.*` 。 >w 在此参数中，通配符 `*` 等价于数字 `0` 。 * **`ip_end（结束ip）`** `(String)` `默认值见方法参数`：用以指定一个IP地址段的 `结束IP地址` 。IP地址或IP地址段的起始地址中允许通配符“ `*` ”。此参数允许通配符 `*` 。 >w 在此参数中，通配符 `*` 等价于数字 `255` 。 # check() ## 说明 **Ip :: check ()** 检查指定的IP或客户端IP地址是否在黑白名单内，并根据配置显示报错或返回值。 ## 参数 * **`ip（ip）`** `(String)` `''`：用以指定需要检测的IP。如果未传入此参数，将用客户端IP地址代替。 ## 返回 `(Bool)` 类型。当客户端IP地址不在白名单范围且位于黑名单范围内时将返回 `FALSE` ，其它情况返回 `TRUE` 。如果传入的IP地址格式错误，将直接返回 `FALSE` 。 # getAll() ## 说明 **Ip :: getAll ( <kbd>传参数组</kbd> )** 获取黑名单或白名单中的所有记录。此方法 `支持` 中文参数名。此方法 `支持` 参数简写。 ## 参数 * **`type（类型）`** `(String)` `<必须>` `可简写`：详见本模块 `公共参数` 部分的说明。 ## 返回 `(Array)` 类型。一个二维数组或不含任何元素的空数组。当所指定类型的名单内有记录时，返回值为 `二维数组` ： 1. 在第一维的数组中，键为从0开始的自增键，值为一个一维数组。 2. 在第二维数组中，第一个元素代表了IP地址段的 `起始` IP地址，第二个元素代表了IP地址段的 `结束` IP地址，第三个元素代表了此记录的 `过期时间` 。当第三个元素为空时，则代表该条记录的有效期是 `永久` 。当所指定类型的名单内没有记录时，返回值为一个 `空数组` 。 # add() ## 说明 **Ip :: add ( <kbd>传参数组</kbd> )** 向指定的名单中添加新记录。此方法 `支持` 中文参数名。 ## 参数 * **`type（类型）`** `(String)` `<必须>`：详见本模块 `公共参数` 部分的说明。 * **`ip_start（起始ip）`** `(String)` `<必须>`：详见本模块 `公共参数` 部分的说明。 * **`ip_end（结束ip）`** `(String)` `NULL`：详见本模块 `公共参数` 部分的说明。 * **`exp_time（过期时间）`** `(Int)` `NULL`：用以指定所添加记录的过期时间。格式为形如1547142941的 `数字时间戳` ，当时间超过了过期时间后，此条记录将 `不会` 被匹配到。当 `未指定此参数` 时，则代表此条记录 `永不过期` ，直至被删除。 ## 返回 `(Bool)` 类型。如果传入的IP地址 `格式错误` ，或传入的时间 `早于` 当前时间（即已过期），将返回 `FALSE` ；否则返回 `TRUE` 。 ## 示例如果想要在2019-05-01 12:59:59之前 `屏蔽` IP地址121.172.200.68，则应该把这个IP地址添加进 `黑名单` 中： ```php $Data=array( 'type'=>'b', 'ip_start'=>'121.172.200.68', 'exp_time'=>strtotime('2019-05-01 12:59:59');//转换为时间戳 ); Ip::Add($Data) ``` 如果想要在 `永久地` 屏蔽IP地址121.172.200.68，则应该把这个IP地址添加进 `黑名单` 中，且不传入 `exp_time` 参数： ```php $Data=array( 'type'=>'b', 'ip_start'=>'121.172.200.68' ); Ip::Add($Data) ``` >w 添加新记录时，如果所指定类型的名单内有 `相同的记录` ，将会 `覆盖` 原有记录。 >d 请勿在黑名单中添加范围过于宽泛的IP地址段，例如传入 `*.*.*.*` 。 > 如果您只希望少数人使用您的应用，那么您可以将这些客户端的IP地址（或地址段）添加进 `白名单` 中，否则 `没有人` 能够使用您的应用（包括您自己）。 # delete() ## 说明 **Ip :: delete ( <kbd>传参数组</kbd> )** 在指定的名单中删除记录。此方法 `支持` 中文参数名。 ## 参数 * **`type（类型）`** `(String)` `<必须>`：详见本模块 `公共参数` 部分的说明。 * **`ip_start（起始ip）`** `(String)` `<必须>`：详见本模块 `公共参数` 部分的说明。 * **`ip_end（结束ip）`** `(String)` `NULL`：详见本模块 `公共参数` 部分的说明。 ## 返回 `(Bool)` 类型。如果传入的IP地址 `格式错误` ，将返回 `FALSE` ；否则，无论所指定类型的名单中是否存在可以被删除的记录，都将返回 `TRUE` 。 >w 请确保传入的 `ip_start` 、`ip_end` 这两个参数的值与您添加记录时所传入的这两个参数的值 `相同` 。也就是说，假设记录中有 `192.168.1.1` ，并且您想删除它，那么您传入 `192.168.1.*` 是 `无效的` 。您必须 `准确地` 传入IP地址（或者IP地址段的范围）。 >w 如果您添加过 `192.168.1.*` 的记录，即名单中存在 `192.168.1.0` - `192.168.1.255` 的地址段，这种情况下，传入 `192.168.1.*` 是能够删除的。 # find() ## 说明 **Ip :: find ( <kbd>传参数组</kbd> )** 查询指定的IP是否在指定类型的名单中。此方法 `支持` 中文参数名。 ## 参数 * **`type（类型）`** `(String)` `<必须>`：详见本模块 `公共参数` 部分的说明。 * **`ip（ip地址）`** `(String)` `<必须>`：用以指定查询的 `确切IP地址` 。本参数 `不允许` 使用通配符 `*` 。 ## 返回 `(Bool)` 类型。如果传入的IP地址 `格式错误` ，或者不在所指定类型的名单内，将返回 `FALSE` 。其它情况将返回 `TRUE` 。 >w 如果传入的IP格式不正确，将直接返回 `FALSE` ，而不会进行查找操作。 # clean() ## 说明 **Ip :: clean ( <kbd>传参数组</kbd> )** 删除指定名单中过期的记录，或者清空指定的名单。此方法 `支持` 中文参数名。此方法 `支持` 参数简写。 ## 参数 * **`type（类型）`** `(String)` `<必须>` `可简写`：详见本模块 `公共参数` 部分的说明。 * **`reset（重置）`** `(Bool)` `<FALSE>`：用以指定是否清空全部记录，当值为 `TRUE` 时清空指定名单中的全部记录；当值为 `FALSE` 时，仅删除过期的记录。 ## 返回无。