diff --git a/reference/curl/constants_curl_setopt.xml b/reference/curl/constants_curl_setopt.xml index 7d4962b43..0d5a9afff 100644 --- a/reference/curl/constants_curl_setopt.xml +++ b/reference/curl/constants_curl_setopt.xml @@ -3697,9 +3697,7 @@ - Sets the maximum number of TCP keep-alive probes. - The default is 9. - Available as of PHP 8.4.0 and cURL 8.9.0. + 设置 TCP 保持活动探测的最大数量。默认值为 9。自 PHP 8.4.0 和 cURL 8.9.0 起可用。 @@ -3721,11 +3719,9 @@ - Set an array of strings to pass to the telnet negotiations. - The variables should be in the format >option=value<. - cURL supports the options TTYPE, - XDISPLOC and NEW_ENV. - Available as of cURL 7.7.0. + 设置要传递给 telnet 协商的由 string 组成的 array。变量应采用 + >option=value< 格式。cURL 支持选项 TTYPE、XDISPLOC + 和 NEW_ENV。自 cURL 7.7.0 起可用。 @@ -3736,14 +3732,10 @@ - Set the blocksize to use for TFTP data transmission. - Valid range is 8-65464 bytes. - The default of 512 bytes is used if this option is not specified. - The specified block size is only used if supported by the remote server. - If the server does not return an option acknowledgment - or returns an option acknowledgment with no block size, - the default of 512 bytes is used. - Available as of cURL 7.19.4. + 设置用于 TFTP 数据传输的块大小。有效范围为 8-65464 + 字节。如果未指定此选项，则使用默认值 512 + 字节。仅当远程服务器支持时才使用指定的块大小。如果服务器未返回选项确认或返回没有块大小的选项确认，则使用默认值 + 512 字节。自 cURL 7.19.4 起可用。 @@ -3781,9 +3773,8 @@ - 允许 cURL 函数执行的最长秒数。 - Defaults to 0, meaning that functions never time out during transfer. - Available as of cURL 7.1.0. + 允许 cURL 函数执行的最长秒数。默认值为 + 0，表示函数在传输过程中永不超时。自 cURL 7.1.0 起可用。 @@ -3794,10 +3785,9 @@ - 允许 cURL 允许执行的最长毫秒数。如果 cURL 编译时使用系统标准的名称解析器（ standard system name - resolver），那部分的连接仍旧使用以秒计的超时解决方案，最小超时时间还是一秒钟。 - Defaults to 0, meaning that functions never time out during transfer. - Available as of cURL 7.16.2. + 允许 cURL 允许执行的最长毫秒数。如果 cURL 编译时使用系统标准的名称解析器（standard system name + resolver），那部分的连接仍旧使用以秒计的超时解决方案，最小超时时间还是一秒钟。默认值为 + 0，表示函数在传输过程中永不超时。自 cURL 7.16.2 起可用。 diff --git a/reference/filter/book.xml b/reference/filter/book.xml index d1a814602..83841e850 100644 --- a/reference/filter/book.xml +++ b/reference/filter/book.xml @@ -1,6 +1,6 @@ - + 数据过滤器 @@ -8,34 +8,33 @@ &reftitle.intro; - - 该扩展通过验证或清理数据来过滤数据。当数据源包含像用户提供的输入数据等未知（或外部）数据时，这尤其有用。例如，这些数据可能来自 HTML 表单。 - - + + 该扩展提供过滤器，用于验证或清理数据。当数据源包含像用户提供的输入数据等未知（或外部）数据时，这尤其有用。例如，这些数据可能来自 HTML 表单。 + + 有两种主要的过滤类型：验证（validation）和清理（sanitization）。 - - - 验证用于验证或检查数据是否符合某些条件。例如，传递 - FILTER_VALIDATE_EMAIL 可以确定数据是否是有效的电子邮件地址，但不会更改数据本身。 - - - 清理将清理数据，因此可能通过移除不需要的字符来改变数据。例如，使用 - FILTER_SANITIZE_EMAIL 会移除电子邮件地址中不适当的字符。也就是说，不会对数据进行验证。 - - - 对于验证和清理，flag是可选的，可以根据需要调整行为。例如，在过滤 URL 时传递 - FILTER_FLAG_PATH_REQUIRED 将要求存在路径（如 http://example.org/foo 中的 /foo）。 - + + + 验证过滤器用于检查数据是否符合某些标准。这些过滤器通过 FILTER_VALIDATE_* + 常量区分。例如，FILTER_VALIDATE_EMAIL 过滤器可用于确定数据是否为有效的电子邮件地址。但是，它永远不会更改输入数据。 + + + 另一方面，清理将“清洁”数据，因此可能会通过添加或移除字符来更改输入数据。这些过滤器通过 FILTER_SANITIZE_* + 常量区分。例如，FILTER_SANITIZE_EMAIL 过滤器将删除电子邮件地址中不应该存在的字符。但是，清理后的数据不会验证是否是有效的电子邮件地址。 + + + 大多数过滤器都支持可选的 flag，这些 flag 可以调整过滤器的行为。这些标记通过 FILTER_FLAG_* + 常量区分。例如，将 FILTER_FLAG_PATH_REQUIRED 与 FILTER_VALIDATE_URL 验证过滤器一起使用，可以要求 URL + 存在路径（例如 https://example.org/foo 中的 /foo）。 + &reference.filter.setup; - &reference.filter.filters; &reference.filter.constants; &reference.filter.examples; &reference.filter.reference; - - + - + &reftitle.constants; &extension.constants; + + 输入常量 + + 这些常量用于 + filter_input 和 + filter_input_array。 + INPUT_POST - (int) + (int) @@ -21,7 +28,7 @@ INPUT_GET - (int) + (int) @@ -32,7 +39,7 @@ INPUT_COOKIE - (int) + (int) @@ -43,7 +50,7 @@ INPUT_ENV - (int) + (int) @@ -54,7 +61,7 @@ INPUT_SERVER - (int) + (int) @@ -69,8 +76,7 @@ - SESSION 变量。 - (暂未实现) + SESSION 变量。（自 PHP 8.0.0 起移除，之前未实现） @@ -81,585 +87,1058 @@ - REQUEST 变量。 - (暂未实现) + REQUEST 变量。（自 PHP 8.0.0 起移除，之前未实现） + + + + 普通过滤 flag FILTER_FLAG_NONE - (int) + (int) - 没有标记。 + 没有 flag。 FILTER_REQUIRE_SCALAR - (int) + (int) - 此标记要求输入的是标量。 + flag 要求过滤的输入是标量。 FILTER_REQUIRE_ARRAY - (int) + (int) - 需要输入的是数组。 + flag 要求过滤的输入是 array。 FILTER_FORCE_ARRAY - (int) + (int) - 一律返回数组。 + 此 flag 将标量输入封装为包含单个元素的 array，以供操作数组的过滤器使用。 FILTER_NULL_ON_FAILURE - (int) - - - - 失败时返回 NULL，而非 FALSE。 - - - - - - FILTER_VALIDATE_INT - (int) - - - - 标记 "int" 过滤器。 - - - - - - FILTER_VALIDATE_BOOL - (int) - - - - FILTER_VALIDATE_BOOLEAN 的别名。 - - - - - - FILTER_VALIDATE_BOOLEAN - (int) + (int) - 标记 "boolean" 过滤器。 + 失败时使用 &null; 而不是 &false;。 - - - - - FILTER_VALIDATE_FLOAT - (int) - - - 标记 "float" 过滤器。 + 可与任何验证 FILTER_VALIDATE_* + 过滤器一起使用。 - - - FILTER_VALIDATE_REGEXP - (int) - - - - 标记 "validate_regexp" 过滤器。 - - - - + + + + 清理过滤器 flag + - FILTER_VALIDATE_URL - (int) + FILTER_FLAG_STRIP_LOW + (int) - 标记 "validate_url" 过滤器。 + 除去 ASCII 值小于 32 的字符。 - + - FILTER_VALIDATE_DOMAIN - (int) + FILTER_FLAG_STRIP_HIGH + (int) - “validate_domain”过滤器的 ID。 - （自 PHP 7.0.0 起可用） + 除去 ASCII 值大于 127 的字符。 - + - FILTER_VALIDATE_EMAIL - (int) + FILTER_FLAG_STRIP_BACKTICK + (int) - 标记 "validate_email" 过滤器。 + 除去反引号（`）字符。 - + - FILTER_VALIDATE_IP - (int) + FILTER_FLAG_ENCODE_LOW + (int) - 标记 "validate_ip" 过滤器。 + 对 ASCII 值小于 32 的字符进行编码。 - + - FILTER_VALIDATE_MAC - (int) + FILTER_FLAG_ENCODE_HIGH + (int) - 标记 "validate_mac_address" 过滤器。 + 对 ASCII 值大于 127 的字符进行编码。 - + - FILTER_DEFAULT - (int) + FILTER_FLAG_ENCODE_AMP + (int) - 标记默认的 "unsafe_raw" 过滤器。 等同于 - FILTER_UNSAFE_RAW。 + 编码 &。 - + - FILTER_UNSAFE_RAW - (int) + FILTER_FLAG_NO_ENCODE_QUOTES + (int) - 标记 "unsafe_raw" 过滤器。 + 单双引号（' 和 "）将不会编码。 - + - FILTER_SANITIZE_STRING - (int) + FILTER_FLAG_EMPTY_STRING_NULL + (int) - 标记 "string" 过滤器。 - （自 PHP 8.1.0 起弃用，使用 htmlspecialchars 替代。） + + 如果字符串清理是空字符串，则将值转换为 &null; - + + + + 验证过滤器 + + - FILTER_SANITIZE_STRIPPED - (int) + FILTER_VALIDATE_BOOL + (int) - 标记 "stripped" 过滤器。 - （自 PHP 8.1.0 起弃用，使用 htmlspecialchars 替代。） + 对于 "1"、"true"、"on" + 和 "yes" 返回 &true;。 - - - - - FILTER_SANITIZE_ENCODED - (int) - - - 标记 "encoded" 过滤器。 + 对于 "0"、"false"、"off"、"no" + 和 "" 返回 &false;。 - - - - - FILTER_SANITIZE_SPECIAL_CHARS - (int) - - - 标记 "special_chars" 过滤器。 + 非 bool 值的返回值取决于 FILTER_NULL_ON_FAILURE。如果设置，则返回 &null;，否则返回 &false;。 - - - - - FILTER_SANITIZE_EMAIL - (int) - - + + 可用选项 + + default + + + 过滤失败时返回的值。 + + + + - 标记 "email" 过滤器。 + 自 PHP 8.0.0 起可用。 - + + - FILTER_SANITIZE_URL - (int) + FILTER_VALIDATE_BOOLEAN + (int) - 标记 "url" 过滤器。 + &Alias; FILTER_VALIDATE_BOOL。该别名在 PHP 8.0.0 中引入其规范名称之前可用。 - + + - FILTER_SANITIZE_NUMBER_INT - (int) + FILTER_VALIDATE_INT + (int) - 标记 "number_int" 过滤器。 + 验证值是否为整数，成功时则转换为 int 类型。 + + + + 字符串值在验证之前使用 trim。 + + + + + 可用选项 + + default + + + 过滤失败时返回的值。 + + + + + min_range + + + 只有当值大于或等于提供的值时，才有效。 + + + + + max_range + + + 只有当该值小于或等于提供的值时，才有效。 + + + + + + 可选 flag + + + FILTER_FLAG_ALLOW_OCTAL + (int) + + + + + 允许八进制整数（0[0-7]+）。 + + + + + + FILTER_FLAG_ALLOW_HEX + (int) + + + + 允许十六进制整数（0x[0-9a-fA-F]+）。 + + + + - + + - FILTER_SANITIZE_NUMBER_FLOAT - (int) + FILTER_VALIDATE_FLOAT + (int) - 标记 "number_float" 过滤器。 + 验证值是否为浮点数，成功时则转换为 float 类型。 + + + + 字符串值在验证之前使用 trim。 + + + + + 可用选项 + + default + + + 过滤失败时返回的值。 + + + + + decimal + + + + + + + + min_range + + + 只有当值大于或等于提供的值时，才有效。自 PHP 7.4.0 起可用。 + + + + + max_range + + + 只有当该值小于或等于提供的值时，才有效。自 PHP 7.4.0 起可用。 + + + + + + 可选 flag + + + FILTER_FLAG_ALLOW_THOUSAND + (int) + + + + 接受逗号（,），通常代表千位分隔符。 + + + + - + - FILTER_SANITIZE_MAGIC_QUOTES - (int) + FILTER_VALIDATE_REGEXP + (int) - 标记 "magic_quotes" 过滤器。 - （自 PHP 7.3.0 起弃用，自 PHP 8.0.0 - 起移除，使用 FILTER_SANITIZE_ADD_SLASHES 替代。） + 根据 regexp 选项提供的正则表达式验证值。 + + + 可用选项 + + default + + + 过滤失败时返回的值。 + + + + + regexp + + + Perl 兼容的正则表达式。 + + + + - + + - FILTER_SANITIZE_ADD_SLASHES - (int) + FILTER_VALIDATE_URL + (int) - “add_slashes”过滤器的 ID。 - (自 PHP 7.3.0 起可用) + 根据 RFC 2396 验证 URL 名称是否有效。 + + 可用选项 + + default + + + 过滤失败时返回的值。 + + + + + + 可选 flag + + + FILTER_FLAG_SCHEME_REQUIRED + (int) + + + + 要求 URL 包含协议部分。 + + + + 自 PHP 7.3.0 起弃用，自 PHP 8.0.0 起移除。这是因为 + FILTER_VALIDATE_URL 过滤器始终隐含。 + + + + + + + FILTER_FLAG_HOST_REQUIRED + (int) + + + + 要求 URL 包含主机部分。 + + + + 自 PHP 7.3.0 起弃用，自 PHP 8.0.0 起移除。这是因为 + FILTER_VALIDATE_URL 过滤器始终隐含。 + + + + + + + FILTER_FLAG_PATH_REQUIRED + (int) + + + + 要求 URL 包含路径部分。 + + + + + + FILTER_FLAG_QUERY_REQUIRED + (int) + + + + 要求 URL 包含查询部分。 + + + + + + + 有效的 URL 可能未指定 HTTP + 协议（http://）。因此，可能需要进一步验证以确定 URL + 是否使用期望的协议，例如 ssh:// 或 mailto:。 + + + + + 此过滤器仅适用于 ASCII URL。这意味着将始终拒绝国际化域名（IDN）。 + + - + - FILTER_CALLBACK - (int) + FILTER_VALIDATE_DOMAIN + (int) - 标记 "callback" 过滤器。 + 根据 RFC 952、RFC + 1034、RFC 1035、RFC + 1123、RFC 2732 和 RFC + 2181 验证域名是否有效。 + + 可用选项 + + default + + + 过滤失败时返回的值。 + + + + + + 可选 flag + + + FILTER_FLAG_HOSTNAME + (int) + + + + 要求主机名以字母数字开头，并且仅包含字母数字或连字符。 + + + + - + - FILTER_FLAG_ALLOW_OCTAL - (int) + FILTER_VALIDATE_EMAIL + (int) - "int" 过滤器允许八进制（octal）标记的字符（0[0-7]+）。 + 验证值是否是“有效”的电子邮件地址。 - - - - - FILTER_FLAG_ALLOW_HEX - (int) - - + - "int" 过滤器允许十六进制（Hex）标记的字符（0x[0-9a-fA-F]+） + 验证是根据 RFC 822 中的 addr-spec + 语法进行的。拒绝注释、空格折叠和无点域名。 + + + 可用选项 + + default + + + 过滤失败时返回的值。 + + + + + + 可选 flag + + + FILTER_FLAG_EMAIL_UNICODE + (int) + + + + 接受 local 部分中的 Unicode 字符。自 PHP 7.1.0 起可用。 + + + + + + + + 电子邮件验证很复杂，确认电子邮件有效且存在的唯一真正方法是向该地址发送电子邮件。 + + - + + - FILTER_FLAG_STRIP_LOW - (int) + FILTER_VALIDATE_IP + (int) - - 过滤 ASCII 编码值大于 32 的字符 。 - + + 验证值为 IP 地址。 + + + 可用选项 + + default + + + 过滤失败时返回的值。 + + + + + + 可选 flag + + + FILTER_FLAG_IPV4 + (int) + + + + 允许 IPv4 地址。 + + + + + + FILTER_FLAG_IPV6 + (int) + + + + 允许 IPv6 地址。 + + + + + + FILTER_FLAG_NO_RES_RANGE + (int) + + + + 拒绝保留地址。 + + + 这些是在 RFC 6890 + 中标记为由协议保留的范围。 + + + IPv4 的对应以下范围： + + 0.0.0.0/8 + 169.254.0.0/16 + 127.0.0.0/8 + 240.0.0.0/4 + . + + + IPv6 的对应以下范围： + + ::1/128 + ::/128 + ::FFFF:0:0/96 + FE80::/10 + . + + + + + + FILTER_FLAG_NO_PRIV_RANGE + (int) + + + + 拒绝私有地址。 + + + IPv4 的对应以下范围： + + 10.0.0.0/8 + 172.16.0.0/12 + 192.168.0.0/16 + . + + + IPv6 地址则以 FD 或 FC 开头。 + + + + + + FILTER_FLAG_GLOBAL_RANGE + (int) + + + + 仅允许全局地址。这些可以在 RFC 6890 + 中找到，其中 Global 属性是 True。自 + PHP 8.2.0 起可用。 + + + + - + + - FILTER_FLAG_STRIP_HIGH - (int) + FILTER_VALIDATE_MAC + (int) - 过滤 ASCII 编码值大于 127 的字符 。 + 验证该值是否是 MAC 地址。 + + + 可用选项 + + default + + + 过滤失败时返回的值。 + + + + - + + + + 清理过滤器 + - FILTER_FLAG_STRIP_BACKTICK - (int) + FILTER_UNSAFE_RAW + (int) - 移除反引号字符。 + 过滤器不执行任何操作。 - - - - - FILTER_FLAG_ENCODE_LOW - (int) - - - 字符的 ASCII 编码值大于 32。 + 但如果与 FILTER_FLAG_STRIP_* 和 + FILTER_FLAG_ENCODE_* 过滤器清理 flag + 一起使用，可以去除或编码特殊字符。 - + - FILTER_FLAG_ENCODE_HIGH - (int) + FILTER_DEFAULT + (int) - 字符的 ASCII 编码值大于 127。 + &Alias; FILTER_UNSAFE_RAW。 - + - FILTER_FLAG_ENCODE_AMP - (int) + FILTER_SANITIZE_STRING + (int) - 为 & 编码。 + 此过滤器会去除标签并对双引号和单引号进行 HTML 编码。 - - - - - FILTER_FLAG_NO_ENCODE_QUOTES - (int) - - - 不要为 ' 和 " 编码。 + 如果与 FILTER_FLAG_STRIP_* 和 + FILTER_FLAG_ENCODE_* + 过滤器清理 flag 一起使用，可以选择性地去除或编码指定字符。 - - - - - FILTER_FLAG_EMPTY_STRING_NULL - (int) - - - (目前不能使用。) + 可以使用 FILTER_FLAG_NO_ENCODE_QUOTES 过滤器 flag 禁用编码引号的行为。 + + + 自 PHP 8.1.0 起弃用，使用 htmlspecialchars 代替。 + + + + + 此过滤器去除标签的方式不等同于 strip_tags。 + + - + - FILTER_FLAG_ALLOW_FRACTION - (int) + FILTER_SANITIZE_STRIPPED + (int) - "number_float" 过滤器允许小数部分。 + &Alias; FILTER_SANITIZE_STRING。 + + + 自 PHP 8.1.0 起弃用，使用 htmlspecialchars 代替。 + + - + - FILTER_FLAG_ALLOW_THOUSAND - (int) + FILTER_SANITIZE_ENCODED + (int) - "number_float" 过滤器允许使用千分位分隔符（,）。 + 此过滤器对字符串进行 URL 编码。 - - - - - FILTER_FLAG_ALLOW_SCIENTIFIC - (int) - - - "number_float" 过滤器允许使用科学计数法（e、E）。 + 如果与 FILTER_FLAG_STRIP_* 和 + FILTER_FLAG_ENCODE_* + 过滤器清理 flag 一起使用，可以选择性地去除或编码指定字符。 - + - FILTER_FLAG_PATH_REQUIRED - (int) + FILTER_SANITIZE_SPECIAL_CHARS + (int) + + 此过滤器对 + + ' + " + < + > + & + + 和 ASCII 值小于 32 的字符进行 HTML 编码。 + - "validate_url" 过滤器，要求带路径部分。 + 如果与 FILTER_FLAG_STRIP_* 过滤器清理 + flag 一起使用，可以选择性地去除指定字符，并且可以使用 FILTER_FLAG_ENCODE_HIGH + 对 ASCII 值大于 127 的字符进行编码。 - + - FILTER_FLAG_QUERY_REQUIRED - (int) + FILTER_SANITIZE_FULL_SPECIAL_CHARS + (int) - "validate_url" 过滤器，要求带 Query 部分。 + 此过滤器相当于调用 htmlspecialchars 并设置 ENT_QUOTES。 - - - - - FILTER_FLAG_SCHEME_REQUIRED - (int) - - - 要求带 scheme 的“validate_url”过滤器。 - （自 PHP 7.3.0 起弃用，且自 PHP 8.0.0 起移除，因为已经隐含在过滤器中。） + 可以使用 FILTER_FLAG_NO_ENCODE_QUOTES 过滤器 flag 禁用编码引号的行为。 + + + 与 htmlspecialchars 一样，此过滤器可识别 default_charset + INI 设置。如果检测到字节序列构成了当前字符集中的无效字符，则会拒绝整个字符串，从而返回空字符串。 + + - + - FILTER_FLAG_HOST_REQUIRED - (int) + FILTER_SANITIZE_EMAIL + (int) - 要求带 host 的“validate_url”过滤器。 - （自 PHP 7.3.0 起弃用，且自 PHP 8.0.0 起移除，因为已经隐含在过滤器中。） + 通过移除除了拉丁字母（[a-zA-Z]）、数字（[0-9]）和特殊字符 + !#$%&'*+-=?^_`{|}~@.[] 之外的所有字符来清理字符串。 - + - FILTER_FLAG_HOSTNAME - (int) + FILTER_SANITIZE_URL + (int) - 要求主机名使用字母数字开头，并且仅包含字母数字或连字符。（自 PHP 7.0.0 起可用）。 + 通过移除除了拉丁字母（[a-zA-Z]）、数字（[0-9]）和特殊字符 + $-_.+!*'(),{}|\\^~[]`<>#%";/?:@&= 之外的所有字符来清理字符串。 - + - FILTER_FLAG_IPV4 - (int) + FILTER_SANITIZE_NUMBER_INT + (int) - "validate_ip" 过滤器，仅仅允许 IPv4 地址。 + 通过移除除了数字（[0-9]）、加号（+）和减号（-）之外的所有字符来清理字符串。 - + - FILTER_FLAG_IPV6 - (int) + FILTER_SANITIZE_NUMBER_FLOAT + (int) - "validate_ip" 过滤器，仅仅允许 IPv6 地址。 + 通过移除除了数字（[0-9]）、加号（+）和减号（-）之外的所有字符来清理字符串。 + + + 可选 flag + + + FILTER_FLAG_ALLOW_FRACTION + (int) + + + + 接受点（.）字符，通常表示为整数部分和小数部分之间的分隔符。 + + + + + + FILTER_FLAG_ALLOW_THOUSAND + (int) + + + + 接受逗号（,）字符，通常代表千位分隔符。 + + + + + + FILTER_FLAG_ALLOW_SCIENTIFIC + (int) + + + + 通过允许 e 和 E 字符来接受科学计数法中的数字。 + + + + + + + 如果未使用 FILTER_FLAG_ALLOW_FRACTION flag，则会移除小数分隔符，从而改变接收到的值。 + + + + +]]> + + &example.outputs; + + + + + - + + - FILTER_FLAG_NO_RES_RANGE - (int) + FILTER_SANITIZE_ADD_SLASHES + (int) - "validate_ip" 过滤器，禁止保留 IP 地址。 + addslashes 应用于输入。自 PHP 7.3.0 起可用。 - + + - FILTER_FLAG_NO_PRIV_RANGE - (int) + FILTER_SANITIZE_MAGIC_QUOTES + (int) - "validate_ip" 过滤器，禁止私有 IP 地址。 + &Alias; FILTER_SANITIZE_ADD_SLASHES。 + + + 自 PHP 7.3.0 起弃用，自 PHP 8.0.0 起移除。 + + - + + + + 用户定义过滤器 + - FILTER_FLAG_EMAIL_UNICODE - (int) + FILTER_CALLBACK + (int) - "validate_email" 过滤器，在邮件地址用户名部分允许 Unicode 字符。 - （PHP 7.1.0 起有效） + 此过滤器将过滤委托给用户定义的函数。callable 作为与 'options' + key 关联的值传递给 options 参数。 + + callback 应具有以下签名： + + mixedcallback + stringvalue + + + + value + + + 需要过滤的值。 + + + + + + + + callback 返回的值作为调用过滤函数返回的值。 + + + + + 使用 <constant>FILTER_CALLBACK</constant> 验证登录名的示例 + + += 5 && ctype_alnum($value)) { + return $value; + } + return null; +} + +$login = "val1dL0gin"; +$filtered_login = filter_var($login, FILTER_CALLBACK, ['options' => 'validate_login']); +var_dump($filtered_login); + +$login = "f&ke login"; +$filtered_login = filter_var($login, FILTER_CALLBACK, ['options' => 'validate_login']); +var_dump($filtered_login); +?> +]]> + + &example.outputs; + + + + + + + 此过滤器不能与其他任何过滤器 flag 一起使用，例如 FILTER_NULL_ON_FAILURE。 + + - - - - - 过滤器类型 - - -
- 验证过滤器 - - - 用于验证的过滤器列表 - - - - ID - 名称 - 选项 - flag - 说明 - - - - - - FILTER_VALIDATE_BOOLEAN、FILTER_VALIDATE_BOOL - - "boolean" - - default - - - FILTER_NULL_ON_FAILURE - - - - "1"、"true"、"on" 和 "yes" 时返回 &true;，否则返回 &false;。 - - - 如果设置了 FILTER_NULL_ON_FAILURE，仅当 "0"、"false"、"off"、"no" - 和 "" 时才会返回 &false;，其它非布尔值都会返回 &null;。 - - - 字符串在对比前会使用 trim 修剪。 - - - - - FILTER_VALIDATE_DOMAIN - "validate_domain" - - default - - - FILTER_FLAG_HOSTNAME、FILTER_NULL_ON_FAILURE - - - - 验证域名标签的长度是否有效。 - - - 根据 RFC 1034、RFC 1035、RFC 952、RFC 1123、RFC 2732、RFC 2181 和 RFC 1123 的规范验证域名。可选的 flag - FILTER_FLAG_HOSTNAME 会添加验证主机名的能力（它们必须以字母数字字符开头，并且只能包含字母数字字符或连字符）。 - - - - - FILTER_VALIDATE_EMAIL - "validate_email" - - default - - - FILTER_FLAG_EMAIL_UNICODE、FILTER_NULL_ON_FAILURE - - - - 验证值是否是有效的电子邮件地址。 - - - 一般情况下，这将根据 RFC 822 对电子邮件地址进行验证，使用 - addr-spec 语法，并且不支持注释、空白折叠和无点域名的例外情况。 - - - - - FILTER_VALIDATE_FLOAT - "float" - - default、decimal、min_range、max_range - - - FILTER_FLAG_ALLOW_THOUSAND、FILTER_NULL_ON_FAILURE - - - - 将值作为浮点数验证，并且可选择在指定范围内进行验证，在验证成功后将其转换为浮点数。 - - - 字符串在对比前会使用 trim 修剪。 - - - - - FILTER_VALIDATE_INT - "int" - - default、min_range、max_range - - - FILTER_FLAG_ALLOW_OCTAL、FILTER_FLAG_ALLOW_HEX、FILTER_NULL_ON_FAILURE - - - - 将值作为整数验证，并且可选择在指定范围内进行验证，在验证成功后将其转换为整数。 - - - 字符串在对比前会使用 trim 修剪。 - - - - - FILTER_VALIDATE_IP - "validate_ip" - - default - - - FILTER_FLAG_IPV4、FILTER_FLAG_IPV6、FILTER_FLAG_NO_PRIV_RANGE、FILTER_FLAG_NO_RES_RANGE、FILTER_FLAG_GLOBAL_RANGE、FILTER_NULL_ON_FAILURE - - - 将值作为 IP 地址验证，可选择仅验证 IPv4、IPv6 或不验证私有、保留范围。 - - - - FILTER_VALIDATE_MAC - "validate_mac_address" - - default - - - FILTER_NULL_ON_FAILURE - - 将值作为 MAC 地址验证。 - - - FILTER_VALIDATE_REGEXP - "validate_regexp" - - default、regexp - - - FILTER_NULL_ON_FAILURE - - - 根据 regexp（Perl 兼容的正则表达式）验证值。 - - - - FILTER_VALIDATE_URL - "validate_url" - - default - - - FILTER_FLAG_SCHEME_REQUIRED、FILTER_FLAG_HOST_REQUIRED、FILTER_FLAG_PATH_REQUIRED、FILTER_FLAG_QUERY_REQUIRED、FILTER_NULL_ON_FAILURE - - - 验证值是否为 URL（根据 &url.rfc;2396），并可选择验证 URL 所需的组件。请注意，有效的 - URL 可能不会指定 HTTP 协议（http://），因此可能需要进一步验证以确定 URL 是否使用了期望的协议，如 ssh:// - 或mailto:。请注意，该函数只会认为 ASCII 编码的 URL 是有效的；国际化域名（包含非 ASCII 字符）将无法通过验证。 - - - - -
- - - - 当将 default 设置到选项，如果值未通过验证，将使用 default 的值。 - - - - - &reftitle.changelog; - - - - - - &Version; - &Description; - - - - - 8.0.0 - - FILTER_VALIDATE_URL 过滤器移除 FILTER_FLAG_SCHEME_REQUIRED - 和 FILTER_FLAG_HOST_REQUIRED flag。 - scheme 和 host 始终（一直以来）必需。 - - - - 8.0.0 - - 新增 FILTER_VALIDATE_BOOL 作为 FILTER_VALIDATE_BOOLEAN - 的别名。优先使用 FILTER_VALIDATE_BOOL。 - - - - 7.4.0 - - FILTER_VALIDATE_FLOAT 新增 min_range 和 max_range 选项。 - - - - 7.0.0 - - 新增 FILTER_FLAG_HOSTNAME 和 FILTER_VALIDATE_DOMAIN。 - - - - - - - - -
- - - -
- 清理过滤器 - - - List of filters for sanitization - - - - ID - Name - Flags - Description - - - - - FILTER_SANITIZE_EMAIL - "email" - - - Remove all characters except letters, digits and - !#$%&'*+-=?^_`{|}~@.[]. - - - - FILTER_SANITIZE_ENCODED - "encoded" - - FILTER_FLAG_STRIP_LOW, - FILTER_FLAG_STRIP_HIGH, - FILTER_FLAG_STRIP_BACKTICK, - FILTER_FLAG_ENCODE_LOW, - FILTER_FLAG_ENCODE_HIGH - - URL-encode string, optionally strip or encode special characters. - - - FILTER_SANITIZE_MAGIC_QUOTES - "magic_quotes" - - - Apply addslashes. - (DEPRECATED as of PHP 7.3.0 and - REMOVED as of PHP 8.0.0, - use FILTER_SANITIZE_ADD_SLASHES instead.) - - - - FILTER_SANITIZE_ADD_SLASHES - "add_slashes" - - Apply addslashes. (Available as of PHP 7.3.0) - - - FILTER_SANITIZE_NUMBER_FLOAT - "number_float" - - FILTER_FLAG_ALLOW_FRACTION, - FILTER_FLAG_ALLOW_THOUSAND, - FILTER_FLAG_ALLOW_SCIENTIFIC - - - Remove all characters except digits, +- and - optionally .,eE. - - - - FILTER_SANITIZE_NUMBER_INT - "number_int" - - - Remove all characters except digits, plus and minus sign. - - - - FILTER_SANITIZE_SPECIAL_CHARS - "special_chars" - - FILTER_FLAG_STRIP_LOW, - FILTER_FLAG_STRIP_HIGH, - FILTER_FLAG_STRIP_BACKTICK, - FILTER_FLAG_ENCODE_HIGH - - - HTML-encode '"<>& and characters with - ASCII value less than 32, optionally strip or encode other special - characters. - - - - FILTER_SANITIZE_FULL_SPECIAL_CHARS - "full_special_chars" - - FILTER_FLAG_NO_ENCODE_QUOTES - - - Equivalent to calling htmlspecialchars with ENT_QUOTES set. Encoding quotes can - be disabled by setting FILTER_FLAG_NO_ENCODE_QUOTES. Like htmlspecialchars, this - filter is aware of the default_charset and if a sequence of bytes is detected that - makes up an invalid character in the current character set then the entire string is rejected resulting in a 0-length string. - When using this filter as a default filter, see the warning below about setting the default flags to 0. - - - - FILTER_SANITIZE_STRING - "string" - - FILTER_FLAG_NO_ENCODE_QUOTES, - FILTER_FLAG_STRIP_LOW, - FILTER_FLAG_STRIP_HIGH, - FILTER_FLAG_STRIP_BACKTICK, - FILTER_FLAG_ENCODE_LOW, - FILTER_FLAG_ENCODE_HIGH, - FILTER_FLAG_ENCODE_AMP - - - Strip tags and HTML-encode double and single quotes, optionally strip - or encode special characters. Encoding quotes can be - disabled by setting FILTER_FLAG_NO_ENCODE_QUOTES. - (Deprecated as of PHP 8.1.0, - use htmlspecialchars instead.) - - - - FILTER_SANITIZE_STRIPPED - "stripped" - - - Alias of "string" filter. - (Deprecated as of PHP 8.1.0, - use htmlspecialchars instead.) - - - - FILTER_SANITIZE_URL - "url" - - - Remove all characters except letters, digits and - $-_.+!*'(),{}|\\^~[]`<>#%";/?:@&=. - - - - FILTER_UNSAFE_RAW - "unsafe_raw" - - FILTER_FLAG_STRIP_LOW, - FILTER_FLAG_STRIP_HIGH, - FILTER_FLAG_STRIP_BACKTICK, - FILTER_FLAG_ENCODE_LOW, - FILTER_FLAG_ENCODE_HIGH, - FILTER_FLAG_ENCODE_AMP - - - Do nothing, optionally strip or encode special characters. This - filter is also aliased to FILTER_DEFAULT. - - - - -
- - - - When using one of these filters as a default filter either through your ini file - or through your web server's configuration, the default flags is set to - FILTER_FLAG_NO_ENCODE_QUOTES. You need to explicitly set - filter.default_flags to 0 to have quotes encoded by default. Like this: - - Configuring the default filter to act like htmlspecialchars - - - - - - - - - &reftitle.changelog; - - - - - - &Version; - &Description; - - - - - 8.1.0 - - FILTER_SANITIZE_STRING and - FILTER_SANITIZE_STRIPPED have been deprecated. - - - - 8.0.0 - - FILTER_SANITIZE_MAGIC_QUOTES has been removed. - - - - 7.3.0 - - FILTER_SANITIZE_ADD_SLASHES was added as a - replacement for FILTER_SANITIZE_MAGIC_QUOTES - - - - 7.3.0 - - FILTER_SANITIZE_MAGIC_QUOTES has been deprecated. - - - - - - - - -
- - - -
- 其它过滤器 - - - List of miscellaneous filters - - - - ID - Name - Options - Flags - Description - - - - - FILTER_CALLBACK - "callback" - callable function or method - All flags are ignored - Call user-defined function to filter data. - - - -
- -
- - - -
- 过滤器 flag - - - - List of filter flags - - - - ID - Used with - Description - - - - - FILTER_FLAG_STRIP_LOW - - FILTER_SANITIZE_ENCODED, - FILTER_SANITIZE_SPECIAL_CHARS, - FILTER_SANITIZE_STRING, - FILTER_UNSAFE_RAW - - - Strips characters that have a numerical value <32. - - - - FILTER_FLAG_STRIP_HIGH - - FILTER_SANITIZE_ENCODED, - FILTER_SANITIZE_SPECIAL_CHARS, - FILTER_SANITIZE_STRING, - FILTER_UNSAFE_RAW - - - Strips characters that have a numerical value >127. - - - - FILTER_FLAG_STRIP_BACKTICK - - FILTER_SANITIZE_ENCODED, - FILTER_SANITIZE_SPECIAL_CHARS, - FILTER_SANITIZE_STRING, - FILTER_UNSAFE_RAW - - - Strips backtick characters. - - - - FILTER_FLAG_ALLOW_FRACTION - - FILTER_SANITIZE_NUMBER_FLOAT - - - Allows a period (.) as a fractional separator in - numbers. - - - - FILTER_FLAG_ALLOW_THOUSAND - - FILTER_SANITIZE_NUMBER_FLOAT, - FILTER_VALIDATE_FLOAT - - - Allows a comma (,) as a thousands separator in - numbers. - - - - FILTER_FLAG_ALLOW_SCIENTIFIC - - FILTER_SANITIZE_NUMBER_FLOAT - - - Allows an e or E for scientific - notation in numbers. - - - - FILTER_FLAG_NO_ENCODE_QUOTES - - FILTER_SANITIZE_STRING - - - If this flag is present, single (') and double - (") quotes will not be encoded. - - - - FILTER_FLAG_ENCODE_LOW - - FILTER_SANITIZE_ENCODED, - FILTER_SANITIZE_STRING, - FILTER_UNSAFE_RAW - - - Encodes all characters with a numerical value <32. - - - - FILTER_FLAG_ENCODE_HIGH - - FILTER_SANITIZE_ENCODED, - FILTER_SANITIZE_SPECIAL_CHARS, - FILTER_SANITIZE_STRING, - FILTER_UNSAFE_RAW - - - Encodes all characters with a numerical value >127. - - - - FILTER_FLAG_ENCODE_AMP - - FILTER_SANITIZE_STRING, - FILTER_UNSAFE_RAW - - - Encodes ampersands (&). - - - - FILTER_NULL_ON_FAILURE - - any FILTER_VALIDATE_* - - - Returns &null; for unrecognized values. - - - - FILTER_FLAG_ALLOW_OCTAL - - FILTER_VALIDATE_INT - - - Regards inputs starting with a zero (0) as octal - numbers. This only allows the succeeding digits to be - 0-7. - - - - FILTER_FLAG_ALLOW_HEX - - FILTER_VALIDATE_INT - - - Regards inputs starting with 0x or - 0X as hexadecimal numbers. This only allows - succeeding characters to be a-fA-F0-9. - - - - FILTER_FLAG_EMAIL_UNICODE - - FILTER_VALIDATE_EMAIL - - - Allows the local part of the email address to contain Unicode characters. - - - - FILTER_FLAG_IPV4 - - FILTER_VALIDATE_IP - - - Allows the IP address to be in IPv4 format. - - - - FILTER_FLAG_IPV6 - - FILTER_VALIDATE_IP - - - Allows the IP address to be in IPv6 format. - - - - FILTER_FLAG_NO_PRIV_RANGE - - FILTER_VALIDATE_IP - - - - Fails validation for the following private IPv4 ranges: - 10.0.0.0/8, 172.16.0.0/12 and - 192.168.0.0/16. - - - Fails validation for the IPv6 addresses starting with - FD or FC. - - - - - FILTER_FLAG_NO_RES_RANGE - - FILTER_VALIDATE_IP - - - - Fails validation for the following reserved IPv4 ranges: - 0.0.0.0/8, 169.254.0.0/16, - 127.0.0.0/8 and 240.0.0.0/4. - - - Fails validation for the following reserved IPv6 ranges: - ::1/128, ::/128, - ::ffff:0:0/96 and fe80::/10. - - - These are the ranges that are marked as Reserved-By-Protocol in - RFC 6890. - - - - - FILTER_FLAG_GLOBAL_RANGE - - FILTER_VALIDATE_IP - - - - Fails validation for non global IPv4/IPv6 ranges as found in - RFC 6890 with the - Global attribute being False. - - - - - FILTER_FLAG_SCHEME_REQUIRED - - FILTER_VALIDATE_URL - - - Requires the URL to contain a scheme part. - - - - FILTER_FLAG_HOST_REQUIRED - - FILTER_VALIDATE_URL - - - Requires the URL to contain a host part. - - - - FILTER_FLAG_PATH_REQUIRED - - FILTER_VALIDATE_URL - - - Requires the URL to contain a path part. - - - - FILTER_FLAG_QUERY_REQUIRED - - FILTER_VALIDATE_URL - - - Requires the URL to contain a query string. - - - - FILTER_REQUIRE_SCALAR - - - - Requires the value to be scalar. - - - - FILTER_REQUIRE_ARRAY - - - - Requires the value to be an array. Filter given will be applied to each - scalar entry of the array. - - - - FILTER_FORCE_ARRAY - - - - If the value is a scalar, it is treated as array with the scalar value - as only element. - - - - -
- - - - &reftitle.changelog; - - - - - - &Version; - &Description; - - - - - 8.2.0 - - FILTER_FLAG_GLOBAL_RANGE as a flag to - FILTER_VALIDATE_IP has been added. - - - - 7.3.0 - - The explicit usage of FILTER_FLAG_SCHEME_REQUIRED - and FILTER_FLAG_HOST_REQUIRED has been deprecated. - - - - 7.1.0 - - FILTER_FLAG_EMAIL_UNICODE has been added. - - - - - - - -
- - - - diff --git a/reference/filter/functions/filter-input-array.xml b/reference/filter/functions/filter-input-array.xml index 967ba8b67..c67b24ccc 100644 --- a/reference/filter/functions/filter-input-array.xml +++ b/reference/filter/functions/filter-input-array.xml @@ -1,12 +1,13 @@ - + - + filter_input_array 获取一系列外部变量，并且可以通过过滤器处理它们 + &reftitle.description; @@ -19,139 +20,49 @@ 这个函数当需要获取很多变量却不想重复调用filter_input时很有用。 + &reftitle.parameters; - - - - type - - - INPUT_GET, INPUT_POST, - INPUT_COOKIE, INPUT_SERVER, or - INPUT_ENV之一。 - - - - - options - - - 一个定义参数的数组。一个有效的键必须是一个包含变量名的string，一个有效的值要么是一个filter type，或者是一个array - 指明了过滤器、标示和选项。如果值是一个数组，那么它的有效的键可以是 filter， - 用于指明 filter type，flags - 用于指明任何想要用于过滤器的标示，或者 options 用于指明任何想要用于过滤器的选项。 - 参考下面的例子来更好的理解这段说明。 - - - 这个参数也可以是一个filter constant的整数。那么数组中的所有变量都会被这个过滤器所过滤。 - - - - - add_empty - - - 在返回值中添加 &null; 作为不存在的键。 - - - - - + + + type + + + INPUT_* 常量之一。 + + + + 在用户对超全局变量进行任何修改之前，正在过滤的超全局变量内容是 SAPI + 提供的“原始”内容。要过滤修改后的超全局变量，请使用 filter_var_array。 + + + + + + + + + + + + &reftitle.returnvalues; - - 成功时包含请求变量值的数组。如果通过 type 指定的输入数组没有值可以填充，当没有指定 - FILTER_NULL_ON_FAILURE flag 时函数返回 &null;，否则为 &false;。其它失败返回 &false;。 - - - 如果过滤失败，数组值将为 &false;，如果变量未设置，返回 &null;。如果使用 FILTER_NULL_ON_FAILURE - flag，变量未设置将返回 &false;，过滤失败将返回 &null;。如果 add_empty 参数为 - &false;，不会为复位的变量添加数组元素。 - - - - - &reftitle.examples; - - - <function>filter_input_array</function> 示例 - - 'libgd