mirror of
https://github.com/php/doc-zh.git
synced 2026-04-27 10:16:00 +02:00
Luffy
1164 lines
34 KiB
XML
1164 lines
34 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
|
<!-- $Revision$ -->
|
|
<!-- EN-Revision: e2f2172bf114599926878017ab2dce356956fa9e Maintainer: daijie Status: ready -->
|
|
<!-- CREDITS: mowangjuanzi -->
|
|
<!-- Generated by xml_proto.php v2.4. Found in /scripts directory of phpdoc. -->
|
|
<appendix xml:id="filter.constants" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
|
|
&reftitle.constants;
|
|
&extension.constants;
|
|
|
|
<variablelist>
|
|
<title>输入常量</title>
|
|
<simpara>
|
|
这些常量用于
|
|
<function>filter_input</function> 和
|
|
<function>filter_input_array</function>。
|
|
</simpara>
|
|
<varlistentry xml:id="constant.input-post">
|
|
<term>
|
|
<constant>INPUT_POST</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
<link linkend="reserved.variables.post">POST</link> 变量。
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.input-get">
|
|
<term>
|
|
<constant>INPUT_GET</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
<link linkend="reserved.variables.get">GET</link> 变量。
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.input-cookie">
|
|
<term>
|
|
<constant>INPUT_COOKIE</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
<link linkend="reserved.variables.cookies">COOKIE</link> 变量。
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.input-env">
|
|
<term>
|
|
<constant>INPUT_ENV</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
<link linkend="reserved.variables.environment">ENV</link> 变量。
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.input-server">
|
|
<term>
|
|
<constant>INPUT_SERVER</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
<link linkend="reserved.variables.server">SERVER</link> 变量。
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.input-session">
|
|
<term>
|
|
<constant>INPUT_SESSION</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
<link linkend="reserved.variables.session">SESSION</link> 变量。（自 PHP 8.0.0 起移除，之前未实现）
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.input-request">
|
|
<term>
|
|
<constant>INPUT_REQUEST</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
<link linkend="reserved.variables.request">REQUEST</link> 变量。（自 PHP 8.0.0 起移除，之前未实现）
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<variablelist xml:id="filter.constants.flags.generic">
|
|
<title>普通过滤 flag</title>
|
|
<varlistentry xml:id="constant.filter-flag-none">
|
|
<term>
|
|
<constant>FILTER_FLAG_NONE</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
没有 flag。
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.filter-require-scalar">
|
|
<term>
|
|
<constant>FILTER_REQUIRE_SCALAR</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
flag 要求过滤的输入是标量。
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.filter-require-array">
|
|
<term>
|
|
<constant>FILTER_REQUIRE_ARRAY</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
flag 要求过滤的输入是 <type>array</type>。
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.filter-force-array">
|
|
<term>
|
|
<constant>FILTER_FORCE_ARRAY</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
此 flag 将标量输入封装为包含单个元素的 <type>array</type>，以供操作数组的过滤器使用。
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.filter-null-on-failure">
|
|
<term>
|
|
<constant>FILTER_NULL_ON_FAILURE</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
失败时使用 &null; 而不是 &false;。
|
|
</simpara>
|
|
<simpara>
|
|
可与任何验证 <constant>FILTER_VALIDATE_<replaceable>*</replaceable></constant>
|
|
过滤器一起使用。
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<variablelist xml:id="filter.constants.flags.sanitization">
|
|
<title>清理过滤器 flag</title>
|
|
<varlistentry xml:id="constant.filter-flag-strip-low">
|
|
<term>
|
|
<constant>FILTER_FLAG_STRIP_LOW</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
除去 ASCII 值小于 32 的字符。
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.filter-flag-strip-high">
|
|
<term>
|
|
<constant>FILTER_FLAG_STRIP_HIGH</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
除去 ASCII 值大于 127 的字符。
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.filter-flag-strip-backtick">
|
|
<term>
|
|
<constant>FILTER_FLAG_STRIP_BACKTICK</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
除去反引号（<literal>`</literal>）字符。
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.filter-flag-encode-low">
|
|
<term>
|
|
<constant>FILTER_FLAG_ENCODE_LOW</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
对 ASCII 值小于 32 的字符进行编码。
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.filter-flag-encode-high">
|
|
<term>
|
|
<constant>FILTER_FLAG_ENCODE_HIGH</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
对 ASCII 值大于 127 的字符进行编码。
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.filter-flag-encode-amp">
|
|
<term>
|
|
<constant>FILTER_FLAG_ENCODE_AMP</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
编码 <literal>&</literal>。
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.filter-flag-no-encode-quotes">
|
|
<term>
|
|
<constant>FILTER_FLAG_NO_ENCODE_QUOTES</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
单双引号（<literal>'</literal> 和 <literal>"</literal>）将不会编码。
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.filter-flag-empty-string-null">
|
|
<term>
|
|
<constant>FILTER_FLAG_EMPTY_STRING_NULL</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
<!-- TODO Document/check which filters accept this flag (FILTER_UNSAFE_RAW and FILTER_SANITIZE_STRING only) -->
|
|
如果字符串清理是空字符串，则将值转换为 &null;
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<variablelist xml:id="filter.constants.validation">
|
|
<title>验证过滤器</title>
|
|
|
|
<varlistentry xml:id="constant.filter-validate-bool">
|
|
<term>
|
|
<constant>FILTER_VALIDATE_BOOL</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
对于 <literal>"1"</literal>、<literal>1</literal>（包括二进制、八进制和十六进制表示法）、<literal>1.0</literal>、<literal>"true"</literal>、<literal>true</literal>、<literal>"on"</literal>
|
|
和 <literal>"yes"</literal> 返回 &true;。
|
|
</simpara>
|
|
<simpara>
|
|
对于 <literal>"0"</literal>、<literal>0</literal>（包括二进制、八进制和十六进制表示法）、<literal>0.0</literal>、<literal>"false"</literal>、<literal>false</literal>、<literal>"off"</literal>、<literal>"no"</literal>
|
|
和 <literal>""</literal> 返回 &false;。
|
|
</simpara>
|
|
<simpara>
|
|
字符串值的比较不区分大小写。非 bool 值的返回值取决于 <constant>FILTER_NULL_ON_FAILURE</constant>。如果设置，则返回 &null;，否则返回 &false;。
|
|
</simpara>
|
|
<variablelist xml:id="filter.constants.validation.bool.options">
|
|
<title>可用选项</title>
|
|
<varlistentry>
|
|
<term><literal>default</literal></term>
|
|
<listitem>
|
|
<simpara>
|
|
过滤失败时返回的值。
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<simpara>
|
|
自 PHP 8.0.0 起可用。
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry xml:id="constant.filter-validate-boolean">
|
|
<term>
|
|
<constant>FILTER_VALIDATE_BOOLEAN</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
&Alias; <constant>FILTER_VALIDATE_BOOL</constant>。该别名在 PHP 8.0.0 中引入其规范名称之前可用。
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry xml:id="constant.filter-validate-int">
|
|
<term>
|
|
<constant>FILTER_VALIDATE_INT</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
验证值是否为整数，成功时则转换为 <type>int</type> 类型。
|
|
</simpara>
|
|
|
|
<note>
|
|
<simpara>
|
|
字符串值在验证之前使用 <function>trim</function>。
|
|
</simpara>
|
|
</note>
|
|
|
|
<variablelist xml:id="filter.constants.validation.int.options">
|
|
<title>可用选项</title>
|
|
<varlistentry>
|
|
<term><literal>default</literal></term>
|
|
<listitem>
|
|
<simpara>
|
|
过滤失败时返回的值。
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><literal>min_range</literal></term>
|
|
<listitem>
|
|
<simpara>
|
|
只有当值大于或等于提供的值时，才有效。
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><literal>max_range</literal></term>
|
|
<listitem>
|
|
<simpara>
|
|
只有当该值小于或等于提供的值时，才有效。
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<variablelist xml:id="filter.constants.validation.int.flags">
|
|
<title>可选 flag</title>
|
|
<varlistentry xml:id="constant.filter-flag-allow-octal">
|
|
<term>
|
|
<constant>FILTER_FLAG_ALLOW_OCTAL</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
<!-- TODO: Check that explicit octal prefix 0o and 0O are allowed -->
|
|
允许八进制整数（<literal>0[0-7]+</literal>）。
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.filter-flag-allow-hex">
|
|
<term>
|
|
<constant>FILTER_FLAG_ALLOW_HEX</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
允许十六进制整数（<literal>0x[0-9a-fA-F]+</literal>）。
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry xml:id="constant.filter-validate-float">
|
|
<term>
|
|
<constant>FILTER_VALIDATE_FLOAT</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
验证值是否为浮点数，成功时则转换为 <type>float</type> 类型。
|
|
</simpara>
|
|
|
|
<note>
|
|
<simpara>
|
|
字符串值在验证之前使用 <function>trim</function>。
|
|
</simpara>
|
|
</note>
|
|
|
|
<variablelist xml:id="filter.constants.validation.float.options">
|
|
<title>可用选项</title>
|
|
<varlistentry>
|
|
<term><literal>default</literal></term>
|
|
<listitem>
|
|
<simpara>
|
|
过滤失败时返回的值。
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><literal>decimal</literal></term>
|
|
<listitem>
|
|
<simpara>
|
|
<!-- TODO -->
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><literal>min_range</literal></term>
|
|
<listitem>
|
|
<simpara>
|
|
只有当值大于或等于提供的值时，才有效。自 PHP 7.4.0 起可用。
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><literal>max_range</literal></term>
|
|
<listitem>
|
|
<simpara>
|
|
只有当该值小于或等于提供的值时，才有效。自 PHP 7.4.0 起可用。
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<variablelist xml:id="filter.constants.validation.float.flags">
|
|
<title>可选 flag</title>
|
|
<varlistentry>
|
|
<term>
|
|
<constant>FILTER_FLAG_ALLOW_THOUSAND</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
接受逗号（<literal>,</literal>），通常代表千位分隔符。
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.filter-validate-regexp">
|
|
<term>
|
|
<constant>FILTER_VALIDATE_REGEXP</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
根据 <literal>regexp</literal> 选项提供的正则表达式验证值。
|
|
</simpara>
|
|
|
|
<variablelist xml:id="filter.constants.validation.regex.options">
|
|
<title>可用选项</title>
|
|
<varlistentry>
|
|
<term><literal>default</literal></term>
|
|
<listitem>
|
|
<simpara>
|
|
过滤失败时返回的值。
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><literal>regexp</literal></term>
|
|
<listitem>
|
|
<simpara>
|
|
<link linkend="book.pcre">Perl 兼容</link>的正则表达式。
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry xml:id="constant.filter-validate-url">
|
|
<term>
|
|
<constant>FILTER_VALIDATE_URL</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
根据 <link xlink:href="&url.rfc;2396">RFC 2396</link> 验证 <acronym>URL</acronym> 是否有效。
|
|
</simpara>
|
|
<variablelist xml:id="filter.constants.validation.url.options">
|
|
<title>可用选项</title>
|
|
<varlistentry>
|
|
<term><literal>default</literal></term>
|
|
<listitem>
|
|
<simpara>
|
|
过滤失败时返回的值。
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<variablelist xml:id="filter.constants.validation.url.flags">
|
|
<title>可选 flag</title>
|
|
<varlistentry xml:id="constant.filter-flag-scheme-required">
|
|
<term>
|
|
<constant>FILTER_FLAG_SCHEME_REQUIRED</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
要求 <acronym>URL</acronym> 包含协议部分。
|
|
</simpara>
|
|
<warning>
|
|
<simpara>
|
|
自 PHP 7.3.0 起<emphasis>弃用</emphasis>，自 PHP 8.0.0 起<emphasis>移除</emphasis>。这是因为
|
|
<constant>FILTER_VALIDATE_URL</constant> 过滤器始终隐含。
|
|
</simpara>
|
|
</warning>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.filter-flag-host-required">
|
|
<term>
|
|
<constant>FILTER_FLAG_HOST_REQUIRED</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
要求 <acronym>URL</acronym> 包含主机部分。
|
|
</simpara>
|
|
<warning>
|
|
<simpara>
|
|
自 PHP 7.3.0 起<emphasis>弃用</emphasis>，自 PHP 8.0.0 起<emphasis>移除</emphasis>。这是因为
|
|
<constant>FILTER_VALIDATE_URL</constant> 过滤器始终隐含。
|
|
</simpara>
|
|
</warning>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.filter-flag-path-required">
|
|
<term>
|
|
<constant>FILTER_FLAG_PATH_REQUIRED</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
要求 <acronym>URL</acronym> 包含路径部分。
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.filter-flag-query-required">
|
|
<term>
|
|
<constant>FILTER_FLAG_QUERY_REQUIRED</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
要求 <acronym>URL</acronym> 包含查询部分。
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<warning>
|
|
<simpara>
|
|
有效的 <acronym>URL</acronym> 可能未指定 <acronym>HTTP</acronym>
|
|
协议（<literal>http://</literal>）。因此，可能需要进一步验证以确定 <acronym>URL</acronym>
|
|
是否使用期望的协议，例如 <literal>ssh://</literal> 或 <literal>mailto:</literal>。
|
|
</simpara>
|
|
</warning>
|
|
<warning>
|
|
<simpara>
|
|
此过滤器仅适用于 <acronym>ASCII</acronym> <acronym>URL</acronym>。这意味着将始终拒绝国际化域名（IDN）。
|
|
</simpara>
|
|
</warning>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.filter-validate-domain">
|
|
<term>
|
|
<constant>FILTER_VALIDATE_DOMAIN</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
根据 <link xlink:href="&url.rfc;952">RFC 952</link>、<link xlink:href="&url.rfc;1034">RFC
|
|
1034</link>、<link xlink:href="&url.rfc;1035">RFC 1035</link>、<link xlink:href="&url.rfc;1034">RFC
|
|
1123</link>、<link xlink:href="&url.rfc;1034">RFC 2732</link> 和 <link xlink:href="&url.rfc;2181">RFC
|
|
2181</link> 验证域名是否有效。
|
|
</simpara>
|
|
<variablelist xml:id="filter.constants.validation.domain.options">
|
|
<title>可用选项</title>
|
|
<varlistentry>
|
|
<term><literal>default</literal></term>
|
|
<listitem>
|
|
<simpara>
|
|
过滤失败时返回的值。
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<variablelist xml:id="filter.constants.validation.domain.flags">
|
|
<title>可选 flag</title>
|
|
<varlistentry xml:id="constant.filter-flag-hostname">
|
|
<term>
|
|
<constant>FILTER_FLAG_HOSTNAME</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
要求主机名以字母数字开头，并且仅包含字母数字或连字符。
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.filter-validate-email">
|
|
<term>
|
|
<constant>FILTER_VALIDATE_EMAIL</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
验证值是否是“有效”的电子邮件地址。
|
|
</simpara>
|
|
|
|
<simpara>
|
|
验证是根据 <link xlink:href="&url.rfc;822">RFC 822</link> 中的 <literal>addr-spec</literal>
|
|
语法进行的。拒绝注释、空格折叠和无点域名。
|
|
</simpara>
|
|
|
|
<variablelist xml:id="filter.constants.validation.email.options">
|
|
<title>可用选项</title>
|
|
<varlistentry>
|
|
<term><literal>default</literal></term>
|
|
<listitem>
|
|
<simpara>
|
|
过滤失败时返回的值。
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<variablelist xml:id="filter.constants.validation.email.flags">
|
|
<title>可选 flag</title>
|
|
<varlistentry xml:id="constant.filter-flag-email-unicode">
|
|
<term>
|
|
<constant>FILTER_FLAG_EMAIL_UNICODE</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
接受 local 部分中的 Unicode 字符。自 PHP 7.1.0 起可用。
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<warning>
|
|
<simpara>
|
|
电子邮件验证很复杂，确认电子邮件有效且存在的唯一真正方法是向该地址发送电子邮件。
|
|
</simpara>
|
|
</warning>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry xml:id="constant.filter-validate-ip">
|
|
<term>
|
|
<constant>FILTER_VALIDATE_IP</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
验证值为 IP 地址。
|
|
</para>
|
|
<variablelist xml:id="filter.constants.validation.ip.options">
|
|
<title>可用选项</title>
|
|
<varlistentry>
|
|
<term><literal>default</literal></term>
|
|
<listitem>
|
|
<simpara>
|
|
过滤失败时返回的值。
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<variablelist xml:id="filter.constants.validation.ip.flags">
|
|
<title>可选 flag</title>
|
|
<varlistentry xml:id="constant.filter-flag-ipv4">
|
|
<term>
|
|
<constant>FILTER_FLAG_IPV4</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
允许 IPv4 地址。
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.filter-flag-ipv6">
|
|
<term>
|
|
<constant>FILTER_FLAG_IPV6</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
允许 IPv6 地址。
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.filter-flag-no-res-range">
|
|
<term>
|
|
<constant>FILTER_FLAG_NO_RES_RANGE</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
拒绝保留地址。
|
|
</simpara>
|
|
<simpara>
|
|
这些是在 <link xlink:href="&url.rfc;6890">RFC 6890</link>
|
|
中标记为<literal>由协议保留</literal>的范围。
|
|
</simpara>
|
|
<para>
|
|
IPv4 的对应以下范围：
|
|
<simplelist type="inline">
|
|
<member><literal>0.0.0.0/8</literal></member>
|
|
<member><literal>169.254.0.0/16</literal></member>
|
|
<member><literal>127.0.0.0/8</literal></member>
|
|
<member><literal>240.0.0.0/4</literal></member>
|
|
</simplelist>.
|
|
</para>
|
|
<para>
|
|
IPv6 的对应以下范围：
|
|
<simplelist type="inline">
|
|
<member><literal>::1/128</literal></member>
|
|
<member><literal>::/128</literal></member>
|
|
<member><literal>::FFFF:0:0/96</literal></member>
|
|
<member><literal>FE80::/10</literal></member>
|
|
</simplelist>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.filter-flag-no-priv-range">
|
|
<term>
|
|
<constant>FILTER_FLAG_NO_PRIV_RANGE</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
拒绝私有地址。
|
|
</simpara>
|
|
<para>
|
|
IPv4 的对应以下范围：
|
|
<simplelist type="inline">
|
|
<member><literal>10.0.0.0/8</literal></member>
|
|
<member><literal>172.16.0.0/12</literal></member>
|
|
<member><literal>192.168.0.0/16</literal></member>
|
|
</simplelist>.
|
|
</para>
|
|
<simpara>
|
|
IPv6 地址则以 <literal>FD</literal> 或 <literal>FC</literal> 开头。
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.filter-flag-global-range">
|
|
<term>
|
|
<constant>FILTER_FLAG_GLOBAL_RANGE</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
仅允许全局地址。这些可以在 <link xlink:href="&url.rfc;6890">RFC 6890</link>
|
|
中找到，其中 <literal>Global</literal> 属性是 <literal>True</literal>。自
|
|
PHP 8.2.0 起可用。
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry xml:id="constant.filter-validate-mac">
|
|
<term>
|
|
<constant>FILTER_VALIDATE_MAC</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
验证该值是否是 MAC 地址。
|
|
</simpara>
|
|
|
|
<variablelist xml:id="filter.constants.validation.mac.options">
|
|
<title>可用选项</title>
|
|
<varlistentry>
|
|
<term><literal>default</literal></term>
|
|
<listitem>
|
|
<simpara>
|
|
过滤失败时返回的值。
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<variablelist xml:id="filter.constants.sanitization">
|
|
<title>清理过滤器</title>
|
|
<varlistentry xml:id="constant.filter-unsafe-raw">
|
|
<term>
|
|
<constant>FILTER_UNSAFE_RAW</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
过滤器不执行任何操作。
|
|
</simpara>
|
|
<simpara>
|
|
但如果与 <constant>FILTER_FLAG_STRIP_<replaceable>*</replaceable></constant> 和
|
|
<constant>FILTER_FLAG_ENCODE_<replaceable>*</replaceable></constant> 过滤器清理 flag
|
|
一起使用，可以去除或编码特殊字符。
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.filter-default">
|
|
<term>
|
|
<constant>FILTER_DEFAULT</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
&Alias; <constant>FILTER_UNSAFE_RAW</constant>。
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.filter-sanitize-string">
|
|
<term>
|
|
<constant>FILTER_SANITIZE_STRING</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
此过滤器会去除标签并对双引号和单引号进行 HTML 编码。
|
|
</simpara>
|
|
<simpara>
|
|
如果与 <constant>FILTER_FLAG_STRIP_<replaceable>*</replaceable></constant> 和
|
|
<constant>FILTER_FLAG_ENCODE_<replaceable>*</replaceable></constant>
|
|
过滤器清理 flag 一起使用，可以选择性地去除或编码指定字符。
|
|
</simpara>
|
|
<simpara>
|
|
可以使用 <constant>FILTER_FLAG_NO_ENCODE_QUOTES</constant> 过滤器 flag 禁用编码引号的行为。
|
|
</simpara>
|
|
<warning>
|
|
<simpara>
|
|
自 PHP 8.1.0 起<emphasis>弃用</emphasis>，使用 <function>htmlspecialchars</function> 代替。
|
|
</simpara>
|
|
</warning>
|
|
<warning>
|
|
<simpara>
|
|
此过滤器去除标签的方式不等同于 <function>strip_tags</function>。
|
|
</simpara>
|
|
</warning>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.filter-sanitize-stripped">
|
|
<term>
|
|
<constant>FILTER_SANITIZE_STRIPPED</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
&Alias; <constant>FILTER_SANITIZE_STRING</constant>。
|
|
</simpara>
|
|
<warning>
|
|
<simpara>
|
|
自 PHP 8.1.0 起<emphasis>弃用</emphasis>，使用 <function>htmlspecialchars</function> 代替。
|
|
</simpara>
|
|
</warning>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.filter-sanitize-encoded">
|
|
<term>
|
|
<constant>FILTER_SANITIZE_ENCODED</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
此过滤器对字符串进行 URL 编码。
|
|
</simpara>
|
|
<simpara>
|
|
如果与 <constant>FILTER_FLAG_STRIP_<replaceable>*</replaceable></constant> 和
|
|
<constant>FILTER_FLAG_ENCODE_<replaceable>*</replaceable></constant>
|
|
过滤器清理 flag 一起使用，可以选择性地去除或编码指定字符。
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.filter-sanitize-special-chars">
|
|
<term>
|
|
<constant>FILTER_SANITIZE_SPECIAL_CHARS</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
此过滤器对
|
|
<simplelist type="inline">
|
|
<member><literal>'</literal></member>
|
|
<member><literal>"</literal></member>
|
|
<member><literal><</literal></member>
|
|
<member><literal>></literal></member>
|
|
<member><literal>&</literal></member>
|
|
</simplelist>
|
|
和 ASCII 值小于 32 的字符进行 HTML 编码。与 <constant>FILTER_SANITIZE_FULL_SPECIAL_CHARS</constant>
|
|
过滤器不同，<constant>FILTER_SANITIZE_SPECIAL_CHARS</constant> 过滤器会忽略
|
|
<constant>FILTER_FLAG_NO_ENCODE_QUOTES</constant> flag。
|
|
</para>
|
|
<simpara>
|
|
如果与 <constant>FILTER_FLAG_STRIP_<replaceable>*</replaceable></constant> 过滤器清理
|
|
flag 一起使用，可以选择性地去除指定字符，并且可以使用 <constant>FILTER_FLAG_ENCODE_HIGH</constant>
|
|
对 ASCII 值大于 127 的字符进行编码。
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.filter-sanitize-full-special-chars">
|
|
<term>
|
|
<constant>FILTER_SANITIZE_FULL_SPECIAL_CHARS</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
此过滤器相当于调用 <function>htmlspecialchars</function> 并设置 <constant>ENT_QUOTES</constant>。
|
|
</simpara>
|
|
<simpara>
|
|
可以使用 <constant>FILTER_FLAG_NO_ENCODE_QUOTES</constant> 过滤器 flag 禁用编码引号的行为。
|
|
</simpara>
|
|
<warning>
|
|
<simpara>
|
|
与 <function>htmlspecialchars</function> 一样，此过滤器可识别 <link linkend="ini.default-charset">default_charset</link>
|
|
INI 设置。如果检测到字节序列构成了当前字符集中的无效字符，则会拒绝整个字符串，从而返回空字符串。
|
|
</simpara>
|
|
</warning>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.filter-sanitize-email">
|
|
<term>
|
|
<constant>FILTER_SANITIZE_EMAIL</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
通过移除除了拉丁字母（<literal>[a-zA-Z]</literal>）、数字（<literal>[0-9]</literal>）和特殊字符
|
|
<literal>!#$%&'*+-=?^_`{|}~@.[]</literal> 之外的所有字符来清理字符串。
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.filter-sanitize-url">
|
|
<term>
|
|
<constant>FILTER_SANITIZE_URL</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
通过移除除了拉丁字母（<literal>[a-zA-Z]</literal>）、数字（<literal>[0-9]</literal>）和特殊字符
|
|
<literal>$-_.+!*'(),{}|\\^~[]`<>#%";/?:@&=</literal> 之外的所有字符来清理字符串。
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.filter-sanitize-number-int">
|
|
<term>
|
|
<constant>FILTER_SANITIZE_NUMBER_INT</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
通过移除除了数字（<literal>[0-9]</literal>）、加号（<literal>+</literal>）和减号（<literal>-</literal>）之外的所有字符来清理字符串。
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.filter-sanitize-number-float">
|
|
<term>
|
|
<constant>FILTER_SANITIZE_NUMBER_FLOAT</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
通过移除除了数字（<literal>[0-9]</literal>）、加号（<literal>+</literal>）和减号（<literal>-</literal>）之外的所有字符来清理字符串。
|
|
</simpara>
|
|
|
|
<variablelist xml:id="filter.constants.sanitization.float.flags">
|
|
<title>可选 flag</title>
|
|
<varlistentry xml:id="constant.filter-flag-allow-fraction">
|
|
<term>
|
|
<constant>FILTER_FLAG_ALLOW_FRACTION</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
接受点（<literal>.</literal>）字符，通常表示为整数部分和小数部分之间的分隔符。
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.filter-flag-allow-thousand">
|
|
<term>
|
|
<constant>FILTER_FLAG_ALLOW_THOUSAND</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
接受逗号（<literal>,</literal>）字符，通常代表千位分隔符。
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.filter-flag-allow-scientific">
|
|
<term>
|
|
<constant>FILTER_FLAG_ALLOW_SCIENTIFIC</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
通过允许 <literal>e</literal> 和 <literal>E</literal> 字符来接受科学计数法中的数字。
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<warning>
|
|
<simpara>
|
|
如果未使用 <constant>FILTER_FLAG_ALLOW_FRACTION</constant> flag，则会移除小数分隔符，从而改变接收到的值。
|
|
</simpara>
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
$number = '12.34';
|
|
|
|
var_dump(filter_var($number, FILTER_SANITIZE_NUMBER_FLOAT));
|
|
var_dump(filter_var($number, FILTER_SANITIZE_NUMBER_FLOAT, FILTER_FLAG_ALLOW_FRACTION));
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
&example.outputs;
|
|
<screen>
|
|
<![CDATA[
|
|
string(4) "1234"
|
|
string(5) "12.34"
|
|
]]>
|
|
</screen>
|
|
</informalexample>
|
|
</warning>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry xml:id="constant.filter-sanitize-add-slashes">
|
|
<term>
|
|
<constant>FILTER_SANITIZE_ADD_SLASHES</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
<function>addslashes</function> 应用于输入。自 PHP 7.3.0 起可用。
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry xml:id="constant.filter-sanitize-magic-quotes">
|
|
<term>
|
|
<constant>FILTER_SANITIZE_MAGIC_QUOTES</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
&Alias; <constant>FILTER_SANITIZE_ADD_SLASHES</constant>。
|
|
</simpara>
|
|
<warning>
|
|
<simpara>
|
|
自 PHP 7.3.0 起<emphasis>弃用</emphasis>，自 PHP 8.0.0 起<emphasis>移除</emphasis>。
|
|
</simpara>
|
|
</warning>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<variablelist>
|
|
<title>用户定义过滤器</title>
|
|
<varlistentry xml:id="constant.filter-callback">
|
|
<term>
|
|
<constant>FILTER_CALLBACK</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
此过滤器将过滤委托给用户定义的函数。<type>callable</type> 作为与 <literal>'options'</literal>
|
|
key 关联的值传递给 <parameter>options</parameter> 参数。
|
|
</simpara>
|
|
<para>
|
|
callback 应具有以下签名：
|
|
<methodsynopsis>
|
|
<type>mixed</type><methodname><replaceable>callback</replaceable></methodname>
|
|
<methodparam><type>string</type><parameter>value</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<variablelist role="function_parameters">
|
|
<varlistentry>
|
|
<term><parameter>value</parameter></term>
|
|
<listitem>
|
|
<simpara>
|
|
需要过滤的值。
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
<note>
|
|
<simpara>
|
|
callback 返回的值作为调用过滤函数返回的值。
|
|
</simpara>
|
|
</note>
|
|
<example>
|
|
<title>
|
|
使用 <constant>FILTER_CALLBACK</constant> 验证登录名的示例
|
|
</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
function validate_login(string $value): ?string
|
|
{
|
|
if (strlen($value) >= 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);
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
&example.outputs;
|
|
<screen>
|
|
<![CDATA[
|
|
string(10) "val1dL0gin"
|
|
NULL
|
|
]]>
|
|
</screen>
|
|
</example>
|
|
<warning>
|
|
<simpara>
|
|
此过滤器不能与其他任何过滤器 flag 一起使用，例如 <constant>FILTER_NULL_ON_FAILURE</constant>。
|
|
</simpara>
|
|
</warning>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</appendix>
|
|
<!-- Keep this comment at the end of the file
|
|
Local variables:
|
|
mode: sgml
|
|
sgml-omittag:t
|
|
sgml-shorttag:t
|
|
sgml-minimize-attributes:nil
|
|
sgml-always-quote-attributes:t
|
|
sgml-indent-step:1
|
|
sgml-indent-data:t
|
|
indent-tabs-mode:nil
|
|
sgml-parent-document:nil
|
|
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
|
|
sgml-exposed-tags:nil
|
|
sgml-local-catalogs:nil
|
|
sgml-local-ecat-files:nil
|
|
End:
|
|
vim600: syn=xml fen fdm=syntax fdl=2 si
|
|
vim: et tw=78 syn=sgml
|
|
vi: ts=1 sw=1
|
|
-->
|