Update filter (php#956)

* Update filter-var.xml * Update filter-var-array.xml * Update examples.xml * Update language-snippets.ent * Update
lufei · Dec 26, 2024 · 4b3efcf · 4b3efcf
1 parent ad81fd9
commit 4b3efcf
Show file tree

Hide file tree

Showing 4 changed files with 269 additions and 189 deletions.
diff --git a/language-snippets.ent b/language-snippets.ent
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: 9b68bf2b63200534e022bc65e800cae6c75abf26 Maintainer: Gregory Status: ready -->
+<!-- EN-Revision: ffd2ef754b37526c0b96e94859d57ce06acfbf41 Maintainer: Gregory Status: ready -->
 <!-- CREDITS: dallas, mowangjuanzi, Luffy -->
 <!-- 请保持此文件与英文文件中相应的每个 ENTITY 行号一一对应以便于对照，修改与更新！ -->
 
@@ -861,6 +861,7 @@ linkend="language.types.boolean">布尔类型</link>章节以获取更多信息
 '>
 
 
+
 <!-- FileInfo -->
 <!ENTITY fileinfo.parameters.finfo '<para xmlns="http://docbook.org/ns/docbook">经 <function>finfo_open</function> 返回的 <classname>finfo</classname> 实例。</para>'>
 <!ENTITY fileinfo.changelog.finfo-object '<row xmlns="http://docbook.org/ns/docbook">
@@ -1678,6 +1679,27 @@ It is strongly recommended to avoid timezone abbreviations.
 
 
 
+<!ENTITY dom.tokenlist.errors '<itemizedlist xmlns="http://docbook.org/ns/docbook">
+ <listitem>
+  <simpara>
+   如果 token 包含 null 字节，抛出 <exceptionname>ValueError</exceptionname>。
+  </simpara>
+ </listitem>
+ <listitem>
+  <simpara>
+   如果 token 是空字符串，抛出 code 为 <constant>Dom\SYNTAX_ERR</constant>
+   的 <exceptionname>Dom\DOMException</exceptionname>。
+  </simpara>
+ </listitem>
+ <listitem>
+  <simpara>
+   如果 token 包含 ASCII 空格，抛出 code 为 <constant>Dom\INVALID_CHARACTER_ERR</constant>
+   的 <exceptionname>Dom\DOMException</exceptionname>。
+  </simpara>
+ </listitem>
+</itemizedlist>'>
+
+
 
 
 
@@ -2671,10 +2693,13 @@ Windows 环境下的 Apache 配置文件中添加路径值时，所有的反斜
 <!-- User streams -->
 <!ENTITY userstream.not.implemented.warning '<para xmlns="http://docbook.org/ns/docbook">调用此方法失败将给出
 <constant>E_WARNING</constant>（未实现）。</para>'>
+
 <!ENTITY userstream.updates.context '<note xmlns="http://docbook.org/ns/docbook"><para>当合法的上下文传递给调用函数时，属性
 <varname linkend="streamwrapper.props.context">streamWrapper::$context</varname>
 会被改变。</para></note>'>
 
+<!ENTITY stream.bucket.param '<parameter>bucket</parameter> 现在期望 <classname>StreamBucket</classname> 实例；之前期望 <classname>stdClass</classname>。'>
+<!ENTITY stream.bucket.return '此函数现在返回 <classname>StreamBucket</classname> 实例；之前返回 <classname>stdClass</classname>。'>
 
 <!-- Gmagick -->
 <!ENTITY gmagick.return.success '成功时返回 &true;。'>
@@ -2719,6 +2744,9 @@ Windows 环境下的 Apache 配置文件中添加路径值时，所有的反斜
 </listitem>
 </varlistentry>'>
 
+
+
+
 <!-- ZIP -->
 <!ENTITY zip.filename.separator '<note xmlns="http://docbook.org/ns/docbook"><simpara>为了最大限度地提高代码可移植性，建议在 ZIP 文件名中使用斜线 (<literal>/</literal>) 做为目录分隔符。</simpara></note>'>
 
@@ -4386,6 +4414,8 @@ local: {
   </para>
 '>
 
+
+
 <!ENTITY strings.comparison.return '
   <simpara xmlns="http://docbook.org/ns/docbook">
    如果 <parameter>string1</parameter> 小于 <parameter>string2</parameter>，则返回小于 0 的值；
@@ -4395,17 +4425,23 @@ local: {
   </simpara>
 '>
 
+
+
+
 <!-- filter snippets -->
+<!-- TODO: Remove -->
 <!ENTITY filter.param.filter '
  <varlistentry xmlns="http://docbook.org/ns/docbook">
   <term><parameter>filter</parameter></term>
   <listitem>
    <para>
-    要应用的过滤器 ID。<xref linkend="filter.filters" /> 手册页面列出了可用的过滤器。
+    要应用的过滤器。可以使用 <constant>FILTER_VALIDATE_<replaceable>*</replaceable></constant> 常量作为验证过滤器，使用
+    <constant>FILTER_SANITIZE_<replaceable>*</replaceable></constant> 或 <constant>FILTER_UNSAFE_RAW</constant>
+    作为清理过滤器，也可以使用 <constant>FILTER_CALLBACK</constant> 作为自定义过滤器。
    </para>
    <para>
-    如果省略，将使用 <constant>FILTER_DEFAULT</constant>，默认等同于
-    <constant>FILTER_UNSAFE_RAW</constant>。这将导致不进行任何默认过滤。
+    默认值为 <constant>FILTER_DEFAULT</constant>，是 <constant>FILTER_UNSAFE_RAW</constant>
+    的别名。这将导致默认情况下不进行过滤。
    </para>
   </listitem>
  </varlistentry>
@@ -4414,6 +4450,8 @@ local: {
 
 
 
+
+
 <!-- csprng snippets -->
 <!ENTITY csprng.sources '
 <para xmlns="http://docbook.org/ns/docbook">

diff --git a/reference/filter/examples.xml b/reference/filter/examples.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: 247c617b3d54ac8b8fcd8d82516a476c751ddafd Maintainer: mowangjuanzi Status: ready -->
+<!-- EN-Revision: ce3a6b07e255897b67c74824aebaf0ccb89b86d3 Maintainer: mowangjuanzi Status: ready -->
 <chapter xml:id="filter.examples" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  &reftitle.examples;
 
@@ -151,17 +151,6 @@ After: [email protected]
     </screen>
    </example>
   </para>
-  <para>
-   <example>
-    <title>配置默认过滤器</title>
-    <programlisting role="php" xml:id="filter.examples.sanitization.default_filter">
-<![CDATA[
-filter.default = full_special_chars
-filter.default_flags = 0
-]]>
-    </programlisting>
-   </example>
-  </para>
  </section>
 
 </chapter>

diff --git a/reference/filter/functions/filter-var-array.xml b/reference/filter/functions/filter-var-array.xml
@@ -1,12 +1,13 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: de9c65c91ff1710d8b2d2ec955caea0162679305 Maintainer: mowangjuanzi Status: ready -->
+<!-- EN-Revision: 53054bf8decc8648cf2e90a493692a161e2371af Maintainer: mowangjuanzi Status: ready -->
 <!-- CREDITS: mowangjuanzi -->
 <refentry xml:id="function.filter-var-array" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
   <refname>filter_var_array</refname>
   <refpurpose>获取多个变量并且过滤它们</refpurpose>
  </refnamediv>
+
  <refsect1 role="description">
   &reftitle.description;
   <methodsynopsis>
@@ -15,50 +16,52 @@
    <methodparam choice="opt"><type class="union"><type>array</type><type>int</type></type><parameter>options</parameter><initializer><constant>FILTER_DEFAULT</constant></initializer></methodparam>
    <methodparam choice="opt"><type>bool</type><parameter>add_empty</parameter><initializer>&true;</initializer></methodparam>
   </methodsynopsis>
-  <para>
-   不需要重复调用 <function>filter_var</function> 就能获取多个变量。
-  </para>
+  <simpara>
+   使用 <constant>FILTER_VALIDATE_<replaceable>*</replaceable></constant> 验证过滤器、<constant>FILTER_SANITIZE_<replaceable>*</replaceable></constant>
+   清理过滤器或自定义过滤器来过滤关联 &array; 的值。
+  </simpara>
  </refsect1>
+
  <refsect1 role="parameters">
   &reftitle.parameters;
-  <para>
-   <variablelist>
-    <varlistentry>
-     <term><parameter>array</parameter></term>
-     <listitem>
-      <para>
-       数组，键为字符串，值为待过滤的数据。
-      </para>
-     </listitem>
-    </varlistentry>
-    <varlistentry>
-     <term><parameter>options</parameter></term>
-     <listitem>
-      <para>
-       一个定义参数的数组。一个有效的键必须是一个包含变量名的<type>string</type>，一个有效的值要么是一个<link
-       linkend="filter.filters">filter type</link>，或者是一个<type>array</type>
-       指明了过滤器、标示和选项。如果值是一个数组，那么它的有效的键可以是 <literal>filter</literal>，
-       用于指明 <link linkend="filter.filters">filter type</link>，<literal>flags</literal> 
-       用于指明任何想要用于过滤器的标示，或者 <literal>options</literal> 用于指明任何想要用于过滤器的选项。
-       参考下面的例子来更好的理解这段说明。
-      </para>
-      <para>
-       这个参数也可以是一个<link
-       linkend="filter.constants">filter constant</link>的整数。那么数组中的所有值都会被这个过滤器所过滤。
-      </para>
-     </listitem>
-    </varlistentry>
-    <varlistentry>
-     <term><parameter>add_empty</parameter></term>
-     <listitem>
-      <para>
-       在返回值中添加 &null; 作为不存在的键。
-      </para>
-     </listitem>
-    </varlistentry>
-   </variablelist>
-  </para>
+  <variablelist>
+   <varlistentry>
+    <term><parameter>array</parameter></term>
+    <listitem>
+     <simpara>
+      关联 &array;，包含要过滤的数据。
+     </simpara>
+    </listitem>
+   </varlistentry>
+   <varlistentry>
+    <term><parameter>options</parameter></term>
+    <listitem>
+     <simpara>
+      要么是选项的关联 <type>array</type>，要么是应用于每个条目的过滤器，可以是使用 <constant>FILTER_VALIDATE_<replaceable>*</replaceable></constant>
+      常量的验证过滤器，也可以是使用 <constant>FILTER_SANITIZE_<replaceable>*</replaceable></constant> 常量的清理过滤器。
+     </simpara>
+     <simpara>
+      选项数组是关联数组，其中 key 对应于数据 <parameter>array</parameter> 中的键，而关联的值要么是应用于该条目的过滤器，要么是描述如何以及应用哪个过滤器到该条目的关联数组。
+     </simpara>
+     <simpara>
+      描述如何应用过滤器的关联数组必须包含 <literal>'filter'</literal>
+      key，其关联的值是要应用的过滤器，<constant>FILTER_VALIDATE_<replaceable>*</replaceable></constant>、<constant>FILTER_SANITIZE_<replaceable>*</replaceable></constant>、<constant>FILTER_UNSAFE_RAW</constant>
+      或 <constant>FILTER_CALLBACK</constant> 常量之一。还可以选择性地包含 <literal>'flags'</literal> key，用于指定适用于过滤器的
+      flag，以及 <literal>'options'</literal> key，用于指定适用于过滤器的任何选项。
+     </simpara>
+    </listitem>
+   </varlistentry>
+   <varlistentry>
+    <term><parameter>add_empty</parameter></term>
+    <listitem>
+     <para>
+      为缺失的 key 添加 &null; 到返回值中。
+     </para>
+    </listitem>
+   </varlistentry>
+  </variablelist>
  </refsect1>
+
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
@@ -76,37 +79,40 @@
 <![CDATA[
 <?php
 
-$data = array(
-    'product_id'    => 'libgd<script>',
-    'component'     => '10',
-    'versions'      => '2.0.33',
-    'testscalar'    => array('2', '23', '10', '12'),
-    'testarray'     => '2',
-);
+$data = [
+    'product_id' => 'libgd<script>',
+    'component'  => '10',
+    'versions'   => '2.0.33',
+    'testscalar' => ['2', '23', '10', '12'],
+    'testarray'  => '2',
+];
 
-$args = array(
+$filters = [
     'product_id'   => FILTER_SANITIZE_ENCODED,
-    'component'    => array('filter'    => FILTER_VALIDATE_INT,
-                            'flags'     => FILTER_FORCE_ARRAY, 
-                            'options'   => array('min_range' => 1, 'max_range' => 10)
-                           ),
-    'versions'     => FILTER_SANITIZE_ENCODED,
+    'component'    => [
+        'filter'   => FILTER_VALIDATE_INT,
+        'flags'    => FILTER_FORCE_ARRAY,
+        'options'  => [
+            'min_range' => 1,
+            'max_range' => 10,
+        ],
+    ],
+    'versions'     => [
+        'filter' => FILTER_SANITIZE_ENCODED
+    ],
+    'testscalar'   => [
+        'filter' => FILTER_VALIDATE_INT,
+        'flags'  => FILTER_REQUIRE_SCALAR,
+    ],
+    'testarray'    => [
+        'filter' => FILTER_VALIDATE_INT,
+        'flags'  => FILTER_FORCE_ARRAY,
+    ],
     'doesnotexist' => FILTER_VALIDATE_INT,
-    'testscalar'   => array(
-                            'filter' => FILTER_VALIDATE_INT,
-                            'flags'  => FILTER_REQUIRE_SCALAR,
-                           ),
-    'testarray'    => array(
-                            'filter' => FILTER_VALIDATE_INT,
-                            'flags'  => FILTER_FORCE_ARRAY,
-                           )
+];
 
-);
+var_dump(filter_var_array($data, $filters));
 
-$myinputs = filter_var_array($data, $args);
-
-var_dump($myinputs);
-echo "\n";
 ?>
 ]]>
     </programlisting>
@@ -123,15 +129,15 @@ array(6) {
   }
   ["versions"]=>
   string(6) "2.0.33"
-  ["doesnotexist"]=>
-  NULL
   ["testscalar"]=>
   bool(false)
   ["testarray"]=>
   array(1) {
     [0]=>
     int(2)
   }
+  ["doesnotexist"]=>
+  NULL
 }
 ]]>
     </screen>
@@ -141,14 +147,19 @@ array(6) {
 
  <refsect1 role="seealso">
   &reftitle.seealso;
-  <para>
-   <simplelist>
-    <member><function>filter_input_array</function></member>
-    <member><function>filter_var</function></member>
-    <member><function>filter_input</function></member>
-    <member><xref linkend="filter.filters"/></member>
-   </simplelist>
-  </para>
+  <simplelist>
+   <member><function>filter_input_array</function></member>
+   <member><function>filter_var</function></member>
+   <member><function>filter_input</function></member>
+   <member>
+    验证过滤器
+    <constant>FILTER_VALIDATE_<replaceable>*</replaceable></constant>
+   </member>
+   <member>
+    清理过滤器
+    <constant>FILTER_SANITIZE_<replaceable>*</replaceable></constant>
+   </member>
+  </simplelist>
  </refsect1>
 
 </refentry>