Update outcontrol

lufei · Jan 23, 2024 · e44fdd5 · e44fdd5
1 parent 64d9d48
commit e44fdd5
Show file tree

Hide file tree

Showing 4 changed files with 93 additions and 84 deletions.
diff --git a/reference/outcontrol/functions/flush.xml b/reference/outcontrol/functions/flush.xml
@@ -1,42 +1,40 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: 6ab6ea465889620fc2a8cdaf7b008cbaed83c523 Maintainer: micky Status: ready -->
+<!-- EN-Revision: 91ab4f5f898023b0eed0e642e1482ac11f749d20 Maintainer: micky Status: ready -->
 <!-- CREDITS: mowangjuanzi -->
 <refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.flush">
  <refnamediv>
   <refname>flush</refname>
-  <refpurpose>刷新系统输出缓冲区</refpurpose>
+  <refpurpose>冲刷系统输出缓冲区</refpurpose>
  </refnamediv>
- 
+
  <refsect1 role="description">
   &reftitle.description;
   <methodsynopsis>
    <type>void</type><methodname>flush</methodname>
    <void/>
   </methodsynopsis>
   <para>
-   刷新 PHP 的系统写入缓冲区，且不管 PHP 使用什么后端（CGI、Web 服务器等）。尝试推送当前输出到浏览器，但有一些警告。
-  </para>
-  <para>
-   <function>flush</function> 无法覆盖 Web 服务器的缓冲方案，并且不会对任何浏览器中的客户端缓冲起作用。也不会对
-   PHP 的用户级别输出缓冲机制起作用。这意味着 <function>ob_flush</function> 应该在 <function>flush</function>
-   之前调用，以刷新缓冲区（如果正在使用）。
-  </para>
-  <para>
-   个别服务器，特别是 Win32，在结果传输到浏览器之前，仍然会缓冲脚本的输出，直到程序结束为止。
-  </para>
-  <para>
-   Apache 的服务器模块（比如 mod_gzip），可能自己进行输出缓冲，这将导致
-   <function>flush</function> 不会将数据立即发送到客户端浏览器。
-  </para>
-  <para>
-   甚至浏览器也会在显示之前进行输入缓冲。例如 Netscape
-   浏览器会在接受到行尾或开始标记之前缓冲文本，且在接收到 &lt;/table&gt; 标记之前，不会渲染出整个表格。
-  </para>
-  <para>
-   Microsoft Internet Explorer 的某些版本只有当接收到的 256
-   个字节的输出以后才开始显示页面，所以必须在刷新之前发送额外的空格来让这些浏览器显示页面。
+   冲刷 PHP 的系统写入缓冲区以及 PHP 使用的后端（CGI、Web 服务器）。在命令行环境中，<function>flush</function>
+   将仅尝试冲刷缓冲区的内容，而在 Web 上下文中，将冲刷 header 和缓冲区的内容。
   </para>
+  <note>
+   <simpara>
+    <function>flush</function> 可能无法重写 Web 服务器的缓冲方案，并且它对浏览器中的任何客户端缓冲没有影响。
+   </simpara>
+  </note>
+  <note>
+   <simpara>
+    此函数对用户级输出处理程序（例如由 <function>ob_start</function> 或 <function>output_add_rewrite_var</function>
+    启动的处理程序）没有任何影响。
+   </simpara>
+  </note>
+  <warning>
+   <simpara>
+    <function>flush</function> 会干扰在 Web 上下文中设置和发送 header 的输出处理程序（例如
+    <function>ob_gzhandler</function>），因为它会在这些处理程序之前发送 header。
+   </simpara>
+  </warning>
  </refsect1>
 
  <refsect1 role="parameters">
@@ -61,7 +59,7 @@
     <member><function>ob_end_clean</function></member>
    </simplelist>
   </para>
- </refsect1> 
+ </refsect1>
 
 </refentry>
 

diff --git a/reference/outcontrol/functions/ob-end-flush.xml b/reference/outcontrol/functions/ob-end-flush.xml
@@ -1,34 +1,31 @@
 <?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-flush">
  <refnamediv>
   <refname>ob_end_flush</refname>
-  <refpurpose>冲刷出（送出）输出缓冲区内容并关闭缓冲区</refpurpose>
+  <refpurpose>
+   冲刷（发送）活动输出处理程序的返回值，并关闭活动输出缓冲区
+  </refpurpose>
  </refnamediv>
- 
+
  <refsect1 role="description">
   &reftitle.description;
   <methodsynopsis>
    <type>bool</type><methodname>ob_end_flush</methodname>
    <void/>
   </methodsynopsis>
   <para>
-   这个函数将送出最顶层缓冲区的内容（如果有），并关闭此缓冲区。如果想进一步处理缓冲区中的内容，必须在
-   <function>ob_end_flush</function> 之前调用 <function>ob_get_contents</function>，因为在调用
-   <function>ob_end_flush</function> 后缓冲区内容被丢弃。
+   该函数调用输出处理程序（使用 <constant>PHP_OUTPUT_HANDLER_FINAL</constant>
+   flag），冲刷（发送）其返回值，丢弃活动输出缓冲区的内容并关闭活动输出缓冲区。
+  </para>
+  <para>
+   如果没有以 <constant>PHP_OUTPUT_HANDLER_REMOVABLE</constant> flag 启动活动输出缓冲区，<function>ob_end_flush</function> 将失败。
   </para>
   <para>
-   输出缓冲区必须带有 <link linkend="constant.php-output-handler-flushable">PHP_OUTPUT_HANDLER_FLUSHABLE</link>
-   和 <link linkend="constant.php-output-handler-removable">PHP_OUTPUT_HANDLER_REMOVABLE</link> flag
-   的 <function>ob_start</function> 启动。否则 <function>ob_end_flush</function> 将不起作用。
+   <function>ob_end_flush</function> 将冲刷（发送）输出处理程序的返回值，即使活动输出缓冲区是在没有
+   <constant>PHP_OUTPUT_HANDLER_FLUSHABLE</constant> flag 的情况下启动的。
   </para>
-  <note>
-   <simpara>
-   这个函数与 <function>ob_get_flush</function> 相似，不同的是 <function>ob_get_flush</function>
-   会把缓冲区中的内容作为字符串返回。
-   </simpara>
-  </note>
  </refsect1>
 
  <refsect1 role="parameters">
@@ -39,14 +36,14 @@
  <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>
 
@@ -75,15 +72,14 @@
    <simplelist>
     <member><function>ob_start</function></member>
     <member><function>ob_get_contents</function></member>
-    <member><function>ob_get_flush</function></member>
     <member><function>ob_flush</function></member>
+    <member><function>ob_get_flush</function></member>
     <member><function>ob_end_clean</function></member>
    </simplelist>
   </para>
- </refsect1> 
+ </refsect1>
 
 </refentry>
-
 <!-- Keep this comment at the end of the file
 Local variables:
 mode: sgml

diff --git a/reference/outcontrol/functions/ob-flush.xml b/reference/outcontrol/functions/ob-flush.xml
@@ -1,23 +1,27 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: 6ab6ea465889620fc2a8cdaf7b008cbaed83c523 Maintainer: mowangjuanzi Status: ready -->
+<!-- EN-Revision: 86b976d5afaf037868174fe5c242e886eb69baa4 Maintainer: mowangjuanzi Status: ready -->
 <refentry xml:id="function.ob-flush" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
   <refname>ob_flush</refname>
-  <refpurpose>冲刷出（送出）输出缓冲区中的内容</refpurpose>
+  <refpurpose>冲刷（发送）活动输出处理程序的返回值</refpurpose>
  </refnamediv>
- 
+
  <refsect1 role="description">
   &reftitle.description;
   <methodsynopsis>
    <type>bool</type><methodname>ob_flush</methodname>
    <void/>
   </methodsynopsis>
   <para>
-   这个函数将送出缓冲区的内容（如果里边有内容的话）。如果想进一步处理缓冲区中的内容，必须在<function>ob_flush</function>之前调用<function>ob_get_contents</function> ，因为在调用<function>ob_flush</function>之后缓冲区内容将被丢弃。
+   该函数调用输出处理程序（使用 <constant>PHP_OUTPUT_HANDLER_FLUSH</constant>
+   flag），冲刷（发送）其返回值并丢弃活动输出缓冲区的内容。
+  </para>
+  <para>
+   该函数不会像 <function>ob_end_flush</function> 或 <function>ob_get_flush</function> 那样关闭活动输出缓冲区。
   </para>
   <para>
-  此函数不会销毁输出缓冲区，而像<function>ob_end_flush</function> 函数会销毁缓冲区。
+   如果没有以 <constant>PHP_OUTPUT_HANDLER_FLUSHABLE</constant> flag 启动的活动输出缓冲区，<function>ob_flush</function> 将失败。
   </para>
  </refsect1>
 
@@ -33,17 +37,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_start</function></member>
     <member><function>ob_get_contents</function></member>
-    <member><function>ob_clean</function></member>
     <member><function>ob_end_flush</function></member>
-    <member><function>ob_end_clean</function></member>
+    <member><function>ob_get_flush</function></member>
+    <member><function>ob_clean</function></member>
    </simplelist>
   </para>
- </refsect1> 
+ </refsect1>
 
 </refentry>
 <!-- Keep this comment at the end of the file

diff --git a/reference/outcontrol/ini.xml b/reference/outcontrol/ini.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: 86e6094e86b84a51d00ab217ac50ce8dde33d82a Maintainer: HonestQiao Status: ready -->
+<!-- EN-Revision: c2c5f47c53f58b5a50b5cc3c30116cb2aecf2d3c Maintainer: HonestQiao Status: ready -->
 <!-- CREDITS: mowangjuanzi -->
 <section xml:id="outcontrol.configuration" xmlns="http://docbook.org/ns/docbook">
  &reftitle.runtime;
@@ -20,28 +20,29 @@
     <tbody>
     <row>
      <entry><link linkend="ini.output-buffering">output_buffering</link></entry>
-     <entry>"0"</entry>
+     <entry><literal>"0"</literal></entry>
      <entry>PHP_INI_PERDIR</entry>
      <entry></entry>
     </row>
     <row>
      <entry><link linkend="ini.output-handler">output_handler</link></entry>
-     <entry>NULL</entry>
+     <entry>&null;</entry>
      <entry>PHP_INI_PERDIR</entry>
      <entry></entry>
     </row>
     <row>
      <entry><link linkend="ini.implicit-flush">implicit_flush</link></entry>
-     <entry>"0"</entry>
+     <entry><literal>"0"</literal></entry>
      <entry>PHP_INI_ALL</entry>
      <entry></entry>
     </row>
     <row>
      <entry><link linkend="ini.url-rewriter.tags">url_rewriter.tags</link></entry>
-     <entry>"a=href,area=href,frame=src,form=,fieldset="</entry>
+     <entry><literal>"form="</literal></entry>
      <entry>PHP_INI_ALL</entry>
-     <entry>在 PHP 7.1.0 之前，用于设置 session 的 trans sid 重写。从 PHP 7.1.0 起，仅用于 
-     <function>output_add_rewrite_var</function>.</entry>
+     <entry>从 PHP 7.1.0 起，此 INI 设置仅影响 <function>output_add_rewrite_var</function>。在 PHP 7.1.0
+     之前，此 INI 设置启用透明会话 id 支持（请参阅 <link 
+     linkend="ini.session.trans-sid-tags">session.trans_sid_tags</link>）。</entry>
     </row>
     <row>
      <entry><link linkend="ini.url-rewriter.hosts">url_rewriter.hosts</link></entry>
@@ -54,9 +55,9 @@
   </table>
    &ini.php.constants;
  </para>
- 
+
  &ini.descriptions.title;
- 
+
  <para>
  <variablelist>
   <varlistentry xml:id="ini.output-buffering">
@@ -66,8 +67,8 @@
    </term>
    <listitem>
     <para>
-     该选项设置为“On”，可以在所有的脚本中启用输出缓冲。如果要限制输出缓冲区的最大值，可将该选项设定为指定的最大字节数（例如
-     output_buffering=4096）。该选项在 PHP-CLI 下总是关闭。
+     通过设置该选项为 <literal>"On"</literal>，来启用所有文件的输出缓冲。如果要限制缓冲区的大小，可以使用允许的最大字节数相对应的数字/数量来代替该指令的值
+     <literal>"On"</literal>。例如 <literal>output_buffering=4096</literal>。该选项在 PHP-CLI 下始终关闭。
     </para>
    </listitem>
   </varlistentry>
@@ -79,16 +80,15 @@
    </term>
    <listitem>
     <para>
-     脚本的所有输出重定向到一个函数。例如，设置 output_handler
-     为 <function>mb_output_handler</function>
-     时，字符的编码将被明确转换为指定的编码。设置任何输出处理函数，都将自动处理输出缓冲。
+     脚本的输出可以重定向到函数。例如设置 <literal>output_handler</literal> 为 <function>mb_output_handler</function>
+     时，字符编码将会明确转换为指定编码。设置任何输出处理程序都会自动打开输出缓冲。
     </para>
     <note>
      <para>
-      不能同时使用 <function>mb_output_handler</function> 和
-      <function>ob_iconv_handler</function>，也不能同时使用
-      <function>ob_gzhandler</function> 和
-      <link linkend="ini.zlib.output-compression">zlib.output_compression</link>。
+      <function>mb_output_handler</function> 和 <function>ob_iconv_handler</function> 不能一起使用，并且 <function>ob_gzhandler</function> 和
+      <link linkend="ini.zlib.output-compression">zlib.output_compression</link> 不能与以下函数一起使用
+      <function>mb_output_handler</function>、<function>ob_gzhandler</function>、<link linkend="ini.zlib.output-compression">zlib.output_compression</link>、“URL
+      重写器”处理程序（请参阅 <link linkend="ini.session.use-trans-sid">session.use_trans_sid</link> 和 <function>output_add_rewrite_var</function>)。
      </para>
     </note>
     <note>
@@ -107,10 +107,9 @@
    <listitem>
     <para>
      默认为 &false;。如将该选项改为 &true;，PHP
-     将使输出层在每段信息块输出后自动刷新。这等同于在每次调用
-     <function>print</function>、<function>echo</function>
-     以及 <literal>HTML</literal> 块之后，调用 PHP 中的
-     <function>flush</function> 函数。
+     将使输出层在每段信息块输出后自动刷新。这等同于在每次调用任何产出输出的函数（比如
+     <function>print</function>、<function>echo</function>）以及每个
+     HTML 块之后，调用 PHP 函数 <function>flush</function>。
     </para>
     <para>
      在 Web 环境中使用 PHP 时，打开这个选项会严重影响性能，通常只推荐在调试时使用。在
@@ -129,19 +128,22 @@
    </term>
    <listitem>
     <simpara>
-     <literal>url_rewriter.tags</literal> 指定哪些 HTML 标签由
-     <function>output_add_rewrite_var</function> 值重写。默认为
-     <literal>a=href,area=href,frame=src,input=src,form=</literal>
+     <literal>url_rewriter.tags</literal> 指定 HTML 标记和属性，其中 URL 由 <function>output_add_rewrite_var</function>
+     值重写。默认为 <literal>"form="</literal>。
     </simpara>
     <simpara>
-     <literal>form</literal> 是特殊标签。添加 <literal>&lt;input hidden="session_id" name="session_name"&gt;</literal>
-     为表单变量。
+     添加 <literal>"form="</literal> 或任何 <literal>form</literal> 属性将向 <literal>form</literal> 添加隐藏的 <literal>input</literal>
+     元素，并为传递给 <function>output_add_rewrite_var</function> 的每个名值对（name-value pair）添加名和值属性。
     </simpara>
+    <caution>
+     <simpara>
+      在 <literal>url_rewriter.tags</literal> 中多次添加相同的标签将仅在 URL 重写过程中使用第一次出现的标签。
+     </simpara>
+    </caution>
     <note>
      <simpara>
-      在 PHP 7.1.0 之前，使用 <link linkend="ini.url-rewriter.tags">url_rewriter.tags</link> 指定
-      <link linkend="ini.session.trans-sid-tags">session.trans_sid_tags</link>。自 PHP 7.1.0
-      起，<literal>fieldset</literal> 不再视为特殊标签。
+      PHP 7.1.0 之前，使用 <link linkend="ini.url-rewriter.tags">url_rewriter.tags</link> 指定
+      <link linkend="ini.session.trans-sid-tags">session.trans_sid_tags</link>。
      </simpara>
     </note>
    </listitem>
@@ -156,7 +158,8 @@
     <simpara>
      <literal>url_rewriter.hosts</literal> 可以指定重写那些主机包含
      <function>output_add_rewrite_var</function> 值。默认是
-     <literal>$_SERVER['HTTP_HOST']</literal>。通过“,”指定多个主机，且每个主机间不能带空格。比如：<literal>php.net,wiki.php.net,bugs.php.net</literal>
+     <literal>$_SERVER['HTTP_HOST']</literal>。通过不包含空格的逗号分隔列表指定多个主机。例如
+     <literal>"php.net,wiki.php.net,bugs.php.net"</literal>。
     </simpara>
    </listitem>
   </varlistentry>