Ip


>i 本文档的最新修订日期是: > **2020-12-27** # Ip ## 模块简述 通过对IP地址( `IPv4` )黑白名单的操作,来允许或阻止程序运行。如要使用本模块,请务必保证Temp目录下的ip-blacklist.php和ip-whitelist.php具有 `读写权限` ,否则将报错。当上述两个文件不存在时,将 `自动建立` 这两个文件。 >d 请勿手动修改这两个文件! ## 模块配置 配置文件位于 `/Config/Ip.php` 。 * **`ExitProgream`** `(Bool)` `TRUE` : 当客户端IP地址位于黑名单范围内时,是否 `终止运行并报错` 。 当值为 `TRUE` 时结束程序运行并报错。 当值为 `FALSE` 时,如果客户端IP地址位于黑名单范围内,Check()方法将返回FALSE,否则返回TRUE。 ## 公共参数 * **`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.*.*` 。 **如果既传入了Start参数,也传入了EndIP参数:** 想要 `确切` 地指定IP地址段的起始IP地址,请传入一个 `标准IP地址` 。 >w 在此参数中,通配符 `*` 等价于数字 `0` 。 * **`ip_end(结束ip)`** `(String)` `默认值见方法参数`: 一个IP地址段的结束IP地址。 此参数允许通配符 `*` 。 >w 在此参数中,通配符 `*` 等价于数字 `255` 。 ## :: Check()方法 ### 语法 **Ip :: Check ()** ### 说明 检查客户端IP地址是否在黑白名单内,并根据配置显示报错或返回值。 ### 参数 无。 ### 返回 `(Bool)` 类型。 如果配置文件中的 `ExitProgream` 配置项值为 `FALSE` ,那么当客户端IP地址不在白名单范围且位于黑名单范围内时将返回 `FALSE` ,其它情况返回 `TRUE` 。 ## :: GetAll()方法 ### 语法 **Ip :: GetAll ( 传参数组 )** ### 说明 获取黑名单或白名单中的所有记录。 此方法 `支持` 中文参数名。 ### 参数 * **`type(类型)`** `(String)` `<必须>`: 详见本模块 `公共参数` 部分的说明。 ### 返回 `(Array)` 类型。 一个二维数组或不含任何元素的空数组。 当所指定类型的名单内有记录时,返回值为 `二维数组` : 1. 在第一维的数组中,键为从0开始的自增键,值为一个一维数组。 2. 在第二维数组中,第一个元素代表了IP地址段的 `起始` IP地址,第二个元素代表了IP地址段的 `结束` IP地址,第三个元素代表了此记录的 `过期时间` 。当第三个元素为空时,则代表该条记录的有效期是 `永久` 。 当所指定类型的名单内没有记录时,返回值为一个 `空数组` 。 ## :: Add()方法 ### 语法 **Ip :: Add ( 传参数组 )** ### 说明 向指定的名单中添加新记录。 此方法 `支持` 中文参数名。 ### 参数 * **`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 ( 传参数组 )** ### 说明 在指定的名单中删除记录。 此方法 `支持` 中文参数名。 ### 参数 * **`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 ( 传参数组 )** ### 说明 查询指定的IP是否在指定类型的名单中。 此方法 `支持` 中文参数名。 ### 参数 * **`type(类型)`** `(String)` `<必须>`: 详见本模块 `公共参数` 部分的说明。 * **`ip(ip地址)`** `(String)` `<必须>`: 用以指定查询的 `确切IP地址` 。 本参数 `不允许` 使用通配符 `*` 。 ### 返回 `(Bool)` 类型。 如果传入的IP地址 `格式错误` ,或者不在所指定类型的名单内,将返回 `FALSE` 。其它情况将返回 `TRUE` 。 >w 如果传入的IP格式不正确,将直接返回 `FALSE` ,而不会进行查找操作。 ## :: Clean()方法 ### 语法 **Ip :: Clean ( 传参数组 )** ### 说明 删除指定名单中过期的记录,或者清空指定的名单。 此方法 `支持` 中文参数名。 ### 参数 * **`type(类型)`** `(String)` `<必须>`: 详见本模块 `公共参数` 部分的说明。 * **`reset(重置)`** `(Bool)` ``: 用以指定是否清空全部记录,当值为 `TRUE` 时清空指定名单中的全部记录;当值为 `FALSE` 时,仅删除过期的记录。 ### 返回 无。