Ip

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