Update outcontrol

lufei · Jan 9, 2024 · ec5ef18 · ec5ef18
1 parent fbb2aa0
commit ec5ef18
Show file tree

Hide file tree

Showing 3 changed files with 106 additions and 45 deletions.
diff --git a/reference/outcontrol/constants.xml b/reference/outcontrol/constants.xml
@@ -1,14 +1,18 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: a0ae28d3bc85f927c22649ebd9a590b921534b7d Maintainer: mowangjuanzi Status: ready -->
+<!-- EN-Revision: af7044e82ac0abe745ce3dfe2169e69a7e8e342f Maintainer: mowangjuanzi Status: ready -->
 <appendix xml:id="outcontrol.constants" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  &reftitle.constants;
  &extension.constants.core;
- <variablelist>
+ <variablelist xml:id="outcontrol.constants.flags-passed-to-handler">
+  <title>传递给输出处理程序的状态 flag</title>
+  <para>
+   下列 flag 作为位掩码的一部分传递给由 <function>ob_start</function> 设置的输出处理程序的第二个（<parameter>phase</parameter>）参数：
+  </para>
   <varlistentry xml:id="constant.php-output-handler-start">
    <term>
     <constant>PHP_OUTPUT_HANDLER_START</constant>
-     (<type>int</type>)
+    (<type>int</type>)
    </term>
    <listitem>
     <para>
@@ -19,29 +23,29 @@
   <varlistentry xml:id="constant.php-output-handler-write">
    <term>
     <constant>PHP_OUTPUT_HANDLER_WRITE</constant>
-     (<type>int</type>)
+    (<type>int</type>)
    </term>
    <listitem>
     <para>
-     表示输出缓冲正在刷新，并且有数据要输出。
+     表示输出缓冲区正在刷新，并且有数据要输出。
     </para>
    </listitem>
   </varlistentry>
   <varlistentry xml:id="constant.php-output-handler-flush">
    <term>
     <constant>PHP_OUTPUT_HANDLER_FLUSH</constant>
-     (<type>int</type>)
+    (<type>int</type>)
    </term>
    <listitem>
     <para>
-     表示缓冲已清空。
+     表示缓冲区已清空。
     </para>
    </listitem>
   </varlistentry>
   <varlistentry xml:id="constant.php-output-handler-clean">
    <term>
     <constant>PHP_OUTPUT_HANDLER_CLEAN</constant>
-     (<type>int</type>)
+    (<type>int</type>)
    </term>
    <listitem>
     <para>
@@ -52,7 +56,7 @@
   <varlistentry xml:id="constant.php-output-handler-final">
    <term>
     <constant>PHP_OUTPUT_HANDLER_FINAL</constant>
-     (<type>int</type>)
+    (<type>int</type>)
    </term>
    <listitem>
     <para>
@@ -63,11 +67,11 @@
   <varlistentry xml:id="constant.php-output-handler-cont">
    <term>
     <constant>PHP_OUTPUT_HANDLER_CONT</constant>
-     (<type>int</type>)
+    (<type>int</type>)
    </term>
    <listitem>
     <para>
-     表示缓冲已清空，但输出缓冲将继续。
+     表示缓冲区已清空，但输出缓冲将继续。
     </para>
     <para>
      这是 <constant>PHP_OUTPUT_HANDLER_WRITE</constant> 的别名。
@@ -77,7 +81,7 @@
   <varlistentry xml:id="constant.php-output-handler-end">
    <term>
     <constant>PHP_OUTPUT_HANDLER_END</constant>
-     (<type>int</type>)
+    (<type>int</type>)
    </term>
    <listitem>
     <para>
@@ -88,54 +92,103 @@
     </para>
    </listitem>
   </varlistentry>
+ </variablelist>
+ <variablelist xml:id="outcontrol.constants.buffer-control-flags">
+  <title>输出缓冲区控制 flag</title>
+  <para>
+   下列 flag 作为位掩码的一部分传递给由 <function>ob_start</function> 设置的输出处理程序的第三个（<parameter>flags</parameter>）参数：
+  </para>
   <varlistentry xml:id="constant.php-output-handler-cleanable">
    <term>
     <constant>PHP_OUTPUT_HANDLER_CLEANABLE</constant>
-     (<type>int</type>)
+    (<type>int</type>)
    </term>
    <listitem>
     <para>
-     控制 <function>ob_start</function> 创建的输出缓冲是否可以清除。
+     控制 <function>ob_start</function> 创建的输出缓冲区是否可以由 <function>ob_clean</function> 清除。这个 flag
+     不能控制 <function>ob_end_clean</function> 或 <function>ob_get_clean</function> 的行为。
     </para>
    </listitem>
   </varlistentry>
   <varlistentry xml:id="constant.php-output-handler-flushable">
    <term>
     <constant>PHP_OUTPUT_HANDLER_FLUSHABLE</constant>
-     (<type>int</type>)
+    (<type>int</type>)
    </term>
    <listitem>
     <para>
-     控制 <function>ob_start</function> 创建的输出缓冲是否可以刷新。
+     控制 <function>ob_start</function> 创建的输出缓冲区是否可以由 <function>ob_flush</function> 刷新。这个 flag
+     不能控制 <function>ob_end_flush</function> 或 <function>ob_get_flush</function> 的行为。
     </para>
    </listitem>
   </varlistentry>
   <varlistentry xml:id="constant.php-output-handler-removable">
    <term>
     <constant>PHP_OUTPUT_HANDLER_REMOVABLE</constant>
-     (<type>int</type>)
+    (<type>int</type>)
    </term>
    <listitem>
     <para>
-     控制 <function>ob_start</function> 创建的输出缓冲是否可以在脚本结束前移除。
+     控制 <function>ob_start</function> 创建的输出缓冲区是否可以在脚本结束前或者调用
+     <function>ob_end_clean</function>、<function>ob_end_flush</function>、<function>ob_get_clean</function> 或 <function>ob_get_flush</function> 移除。
     </para>
    </listitem>
   </varlistentry>
   <varlistentry xml:id="constant.php-output-handler-stdflags">
    <term>
     <constant>PHP_OUTPUT_HANDLER_STDFLAGS</constant>
-     (<type>int</type>)
+    (<type>int</type>)
    </term>
    <listitem>
     <para>
-     输出缓冲 flag 的默认设置；当前等同于
+     输出缓冲区 flag 的默认设置；当前等同于
      <constant>PHP_OUTPUT_HANDLER_CLEANABLE</constant> |
      <constant>PHP_OUTPUT_HANDLER_FLUSHABLE</constant> |
      <constant>PHP_OUTPUT_HANDLER_REMOVABLE</constant>.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
+ <variablelist xml:id="outcontrol.constants.flags-returned-by-handler">
+  <title>输出处理程序状态 flag</title>
+  <para>
+   下列 flag 是由 <function>ob_get_status</function> 返回的 <literal>flags</literal> 位掩码的一部分：
+  </para>
+  <varlistentry xml:id="constant.php-output-handler-started">
+   <term>
+    <constant>PHP_OUTPUT_HANDLER_STARTED</constant>
+    (<type>int</type>)
+   </term>
+   <listitem>
+    <para>
+     表示输出处理程序已调用。
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry xml:id="constant.php-output-handler-disabled">
+   <term>
+    <constant>PHP_OUTPUT_HANDLER_DISABLED</constant>
+    (<type>int</type>)
+   </term>
+   <listitem>
+    <para>
+     表示输出处理程序已禁用。当输出处理程序返回 &false; 或者处理缓冲区失败时设置此
+     flag，也有一个情况就是在调用输出处理程序之前设置了此 flag。
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry xml:id="constant.php-output-handler-processed">
+   <term>
+    <constant>PHP_OUTPUT_HANDLER_PROCESSED</constant>
+    (<type>int</type>)
+   </term>
+   <listitem>
+    <para>
+     表示输出处理程序已经成功处理了缓冲区。
+    </para>
+   </listitem>
+  </varlistentry>
+ </variablelist>
 </appendix>
 
 <!-- Keep this comment at the end of the file

diff --git a/reference/outcontrol/functions/ob-clean.xml b/reference/outcontrol/functions/ob-clean.xml
@@ -1,11 +1,11 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: 6ab6ea465889620fc2a8cdaf7b008cbaed83c523 Maintainer: daijie Status: ready -->
+<!-- EN-Revision: 86b976d5afaf037868174fe5c242e886eb69baa4 Maintainer: daijie Status: ready -->
 <!-- CREDITS: mowangjuanzi -->
 <refentry xml:id="function.ob-clean" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
   <refname>ob_clean</refname>
-  <refpurpose>清空（擦掉）输出缓冲区</refpurpose>
+  <refpurpose>清空（擦掉）活动输出缓冲区的内容</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
@@ -15,16 +15,14 @@
    <void/>
   </methodsynopsis>
   <para>
-   此函数用来丢弃输出缓冲区中的内容。
+   此函数调用输出处理程序（使用 <constant>PHP_OUTPUT_HANDLER_CLEAN</constant>
+   flag），丢弃返回值并清除（擦除）活动输出区的内容。
   </para>
   <para>
-   此函数不会像 <function>ob_end_clean</function> 函数那样销毁输出缓冲区。
+   此函数不会像 <function>ob_end_clean</function> 或 <function>ob_get_clean</function> 那样关闭输出缓冲区。
   </para>
   <para>
-   输出缓冲必须已被
-   <function>ob_start</function> 以 <link
-   linkend="constant.php-output-handler-cleanable">PHP_OUTPUT_HANDLER_CLEANABLE</link>
-   标记启动。否则 <function>ob_clean</function> 不会有效果。
+   如果没有以 <constant>PHP_OUTPUT_HANDLER_CLEANABLE</constant> flag 启动的活动输出缓冲区，<function>ob_clean</function> 将失败。
   </para>
  </refsect1>
 
@@ -40,16 +38,25 @@
   </para>
  </refsect1>
 
+ <refsect1 role="errors">
+  &reftitle.errors;
+  <para>
+   如果函数失败会生成 <constant>E_NOTICE</constant>。
+  </para>
+ </refsect1>
+
  <refsect1 role="seealso">
   &reftitle.seealso;
   <para>
    <simplelist>
-    <member><function>ob_flush</function></member>
-    <member><function>ob_end_flush</function></member>
+    <member><function>ob_start</function></member>
+    <member><function>ob_get_contents</function></member>
     <member><function>ob_end_clean</function></member>
+    <member><function>ob_get_clean</function></member>
+    <member><function>ob_flush</function></member>
    </simplelist>
   </para>
- </refsect1> 
+ </refsect1>
 
 </refentry>
 <!-- Keep this comment at the end of the file

diff --git a/reference/outcontrol/functions/ob-end-clean.xml b/reference/outcontrol/functions/ob-end-clean.xml
@@ -1,10 +1,10 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: 6ab6ea465889620fc2a8cdaf7b008cbaed83c523 Maintainer: mowangjuanzi Status: ready -->
+<!-- EN-Revision: 86b976d5afaf037868174fe5c242e886eb69baa4 Maintainer: mowangjuanzi Status: ready -->
 <refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.ob-end-clean">
  <refnamediv>
   <refname>ob_end_clean</refname>
-  <refpurpose>清空（擦除）缓冲区并关闭输出缓冲</refpurpose>
+  <refpurpose>清空（擦除）活动缓冲区的内容并关闭它</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
@@ -14,14 +14,14 @@
    <void/>
   </methodsynopsis>
   <para>
-   此函数丢弃最顶层输出缓冲区的内容并关闭这个缓冲区。如果想要进一步处理缓冲区的内容，必须在
-   <function>ob_end_clean</function> 之前调用 <function>ob_get_contents</function>，因为当调用
-   <function>ob_end_clean</function> 时缓冲区内容将被丢弃。
+   该函数调用输出处理程序（使用 <constant>PHP_OUTPUT_HANDLER_CLEAN</constant> 和 <constant>PHP_OUTPUT_HANDLER_FINAL</constant>
+   flag），丢弃它的返回值，丢弃活动输出缓冲区的内容并关闭活动输出缓冲区。
   </para>
   <para>
-   输出缓冲区必须由带有 <link linkend="constant.php-output-handler-cleanable">PHP_OUTPUT_HANDLER_CLEANABLE</link>
-   和 <link linkend="constant.php-output-handler-removable">PHP_OUTPUT_HANDLER_REMOVABLE</link> flag
-   的 <function>ob_start</function> 启动。否则 <function>ob_end_clean</function> 将不起作用。
+   如果没有以 <constant>PHP_OUTPUT_HANDLER_REMOVABLE</constant> flag 启动的活动输出缓冲区，<function>ob_end_clean</function> 将失败。
+  </para>
+  <para>
+   <function>ob_end_clean</function> 将丢弃活动输出缓冲区的内容，即使是在没有 <constant>PHP_OUTPUT_HANDLER_CLEANABLE</constant> flag 的情况下启动的。
   </para>
  </refsect1>
 
@@ -33,21 +33,21 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   &return.success; 错误的原因首先是，在调用时没有一个起作用的缓冲区，或者是因为某些原因缓冲区不能被删除（可能对特殊缓冲区而言）。   
+   &return.success;
   </para>
  </refsect1>
 
  <refsect1 role="errors">
   &reftitle.errors;
   <para>
-  如果函数失败了，将引发一个<constant>E_NOTICE</constant>异常。
+   如果函数失败了，将生成 <constant>E_NOTICE</constant> 异常。
   </para>
  </refsect1>
 
  <refsect1 role="examples">
   &reftitle.examples;
   <para>
-  下面的例子给出了一种去除所有输出缓冲区的方法：   
+  下面的示例展示了去除活动输出缓冲内容的简单方法：   
   </para>
   <para>
    <example>
@@ -71,13 +71,14 @@ ob_end_clean();
    <simplelist>
     <member><function>ob_start</function></member>
     <member><function>ob_get_contents</function></member>
-    <member><function>ob_flush</function></member>
+    <member><function>ob_clean</function></member>
+    <member><function>ob_get_clean</function></member>
+    <member><function>ob_end_flush</function></member>
    </simplelist>
   </para>
- </refsect1> 
+ </refsect1>
 
 </refentry>
-
 <!-- Keep this comment at the end of the file
 Local variables:
 mode: sgml