user-level-output-buffers.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 2a8768782512db2b95e5da2f032dd0347806d203 Maintainer: mowangjuanzi Status: ready -->
<!-- CREDITS: Luffy -->
<chapter xml:id="outcontrol.user-level-output-buffers" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude">
 <title>用户级输出缓冲区</title>
 <para>
  用户级输出缓冲区可以从 PHP 代码中启动、操作和终止。
  每个缓冲区都包括一个输出缓冲区和一个关联的输出处理程序函数。
 </para>

 <section xml:id="outcontrol.what-output-is-buffered">
  <title>什么输出会被缓冲？</title>
  <para>
   PHP 的用户级输出缓冲区在启动后缓冲所有输出，直到关闭或脚本结束。
   在 PHP 的用户级输出缓冲区的上下文中，输出是指 PHP 将显示或发送回浏览器的所有内容。
   在实际应用中，输出为非零长度的数据，即：
   <itemizedlist>
    <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('outputcontrol.what-is-output')/*)"><xi:fallback/></xi:include>
   </itemizedlist>
  </para>
  <note>
   <simpara>
    用户级输出缓冲区不会捕获直接写入 <literal>stdout</literal> 或传递给具有类似功能的 SAPI 函数的数据。这包括使用
    <function>fwrite</function> 将数据写入 <literal>stdout</literal> 或使用 <function>header</function>
    或 <function>setcookie</function> 发送的 header。
   </simpara>
  </note>
 </section>

 <section>
  <title>打开输出缓冲</title>
  <para>
   可以通过使用 <function>ob_start</function> 函数或设置 <link linkend="ini.output-buffering">output_buffering</link> 和
   <link linkend="ini.output-handler">output_handler</link> &php.ini; 配置来启用输出缓冲。虽然两者都可以创建输出缓冲区，但 <function>ob_start</function>
   更加灵活，因为接受用户定义的函数作为输出处理程序，并且还可以设置对缓冲区允许的操作（冲刷、清空、移除）。通过 <function>ob_start</function>
   开始的缓冲区将从调用该函数的行开始生效，而通过 <link linkend="ini.output-buffering">output_buffering</link> 开始的缓冲区将从脚本的第一行开始缓冲输出。
  </para>
  <para>
   PHP 还自带了内置的 <literal>"URL-Rewriter"</literal> 输出处理程序，它会启动自己的输出缓冲区，并且任何时候最多只允许有两个实例运行（一个用于用户级别的
   URL 重写，另一个用于透明 Session ID 支持）。这些缓冲区可以通过调用 <function>output_add_rewrite_var</function> 函数或启用
   <link linkend="ini.session.use-trans-sid">session.use_trans_sid</link> php.ini 设置来启动。
  </para>
  <para>
   捆绑的 <literal>zlib</literal> 扩展有自己的输出缓冲区，可以使用
   <link linkend="ini.zlib.output-compression">zlib.output_compression</link>
   &php.ini; 设置启用。
  </para>
  <note>
   <simpara>
    <literal>"URL-Rewriter"</literal> 的特殊之处在于同时只允许运行最多两个实例，但所有用户级输出缓冲区都使用 <function>ob_start</function>
    所使用的相同底层缓冲区，并通过自定义的输出处理函数来实现其功能。因此，它们的所有功能都可以由用户级代码模拟。
   </simpara>
  </note>
 </section>

 <section xml:id="outcontrol.nesting-output-buffers">
  <title>嵌套输出缓冲区</title>
  <para>
   如果在启动新的缓冲区时已经存在一个活跃的输出缓冲区，那么新的缓冲区将会嵌套在先前活跃的缓冲区内。无论是否嵌套，内部缓冲区的行为都将保持一致，外部缓冲区不会再次缓冲内部的缓冲输出。只有当内部缓冲区冲刷的输出才会被外部缓冲区缓冲。
  </para>
  <para>
   大多数 <literal>ob_*</literal> 函数只能与活跃的输出缓冲区（最后一个启动的）一起使用，
   因此只能冲刷、清空和关闭活跃的缓冲区。可以使用的函数有
   <function>ob_list_handlers</function>，它返回所有正在使用的输出处理程序的列表，
   以及 <function>ob_get_status</function>，它可以返回活跃缓冲区的信息或所有正在使用的缓冲区的信息。
  </para>
  <para>
   调用 <function>ob_get_level</function> 或 <function>ob_get_status</function> 将返回活跃输出缓冲区的嵌套级别。
  </para>
  <caution>
   <simpara>
    <function>ob_get_level</function> 和 <function>ob_get_status</function> 之间相同级别的值相差一。
    对于 <function>ob_get_level</function>，第一个级别是 <literal>1</literal>，
    而对于 <function>ob_get_status</function>，第一个级别是 <literal>0</literal>。
   </simpara>
  </caution>
 </section>

 <section xml:id="outcontrol.buffer-size">
  <title>缓冲区大小</title>
  <para>
   缓冲区大小由整数表示，表示缓冲区可以存储的字节数，而不会刷新。
   当缓冲区中的输出大小超过缓冲区的大小时，缓冲区的内容将被发送到输出处理程序，其返回值将被刷新，缓冲区将被清除。
  </para>
  <para>
   除了 <literal>"URL-Rewriter"</literal> 之外，输出缓冲区的大小可以在启动缓冲区时设置。
   如果设置为 <literal>0</literal>，则输出缓冲区仅受 PHP 可用内存的限制。
   如果设置为 <literal>1</literal>，则在生成任何非零长度输出的代码块后，缓冲区将被刷新。
  </para>
  <para>
   输出缓冲区的大小可通过调用 <function>ob_get_status</function> 来获取。
  </para>
  <para>
   使用 <function>ob_start</function> 启动的输出缓冲区将其缓冲区大小设置为传递给函数的第二个
   <parameter>chunk_size</parameter> 参数的整数值。
   如果省略，则设置为 <literal>0</literal>。
  </para>
  <para>
   以 <literal>"On"</literal> 设置 <link linkend="ini.output-buffering">output_buffering</link>
   启动的输出缓冲区将其缓冲区大小设置为 <literal>0</literal>。
   如果设置为整数，则缓冲区大小将与该数字对应。
  </para>
  <para>
   <literal>"URL-Rewriter"</literal> 的缓冲区大小设置为 <literal>0</literal>，
   因此仅受 PHP 可用内存的限制。
  </para>
  <para>
   <literal>zlib</literal> 的输出缓冲区大小由
   <link linkend="ini.zlib.output-compression">zlib.output_compression</link>
   &php.ini; 设置控制。
   如果设置为 <literal>"On"</literal>，缓冲区大小将为
   <literal>"16K"</literal>/<literal>16384</literal>。
   如果设置为整数，则缓冲区大小将与该数字（字节）对应。
  </para>
 </section>

 <section xml:id="outcontrol.operations-on-buffers">
  <title>缓冲区中允许的操作</title>
  <para>
   可以通过将
   <link linkend="outcontrol.constants.buffer-control-flags">缓冲区控制标志</link>
   之一传递给 <function>ob_start</function> 的第三个
   <parameter>flags</parameter> 参数来控制缓冲区上允许的操作。
   如果省略，则默认情况下允许所有操作。
   如果使用 <literal>0</literal>，则缓冲区不能被刷新、清空或移除，但仍然可以检索其内容。
  </para>
  <para>
   <constant>PHP_OUTPUT_HANDLER_CLEANABLE</constant> 允许
   <function>ob_clean</function> 清空缓冲区的内容。
  </para>
  <warning>
   <simpara>
    缺少 <constant>PHP_OUTPUT_HANDLER_CLEANABLE</constant> 标志
    不会阻止 <function>ob_end_clean</function>
    或 <function>ob_get_clean</function> 清空缓冲区的内容。
   </simpara>
  </warning>
  <para>
   <constant>PHP_OUTPUT_HANDLER_FLUSHABLE</constant> 允许
   <function>ob_flush</function> 刷新缓冲区的内容。
  </para>
  <warning>
   <simpara>
    缺少 <constant>PHP_OUTPUT_HANDLER_FLUSHABLE</constant> 标志
    不会阻止 <function>ob_end_flush</function>
    或 <function>ob_get_flush</function> 刷新缓冲区的内容。
   </simpara>
  </warning>
  <para>
   <constant>PHP_OUTPUT_HANDLER_REMOVABLE</constant> 允许
   <function>ob_end_clean</function>、<function>ob_end_flush</function>、
   <function>ob_get_clean</function> 或 <function>ob_get_flush</function>
   关闭缓冲区。
  </para>
  <para>
   <constant>PHP_OUTPUT_HANDLER_STDFLAGS</constant>
   这三个标志的组合将允许对缓冲区执行这三个操作。
  </para>
 </section>

 <section>
  <title>冲刷、访问和清理缓冲区内容</title>
  <para>
   冲刷会发送并丢弃活动缓冲区中的内容。当输出的大小超过缓冲区大小时，或者在脚本结束时，又或者是调用了
   <function>ob_flush</function>、<function>ob_end_flush</function> 或
   <function>ob_get_flush</function> 函数时，会冲刷输出缓冲区。
  </para>
  <caution>
   <simpara>
    调用 <function>ob_end_flush</function>
    或 <function>ob_get_flush</function> 将关闭活跃的缓冲区。
   </simpara>
  </caution>
  <caution>
   <simpara>
    冲刷缓冲区将冲刷输出处理程序的返回值，这可能与缓冲区的内容不同。
    例如，使用 <function>ob_gzhandler</function> 将压缩输出并冲刷压缩后的输出。
   </simpara>
  </caution>
  <para>
   可以通过调用 <function>ob_get_contents</function>、<function>ob_get_clean</function>
   或 <function>ob_get_flush</function> 来检索活动缓冲区的内容。
  </para>
  <para>
   如果只需要缓冲区内容的长度，<function>ob_get_length</function> 或
   <function>ob_get_status</function> 将返回内容的字节长度。
  </para>
  <caution>
   <simpara>
    调用 <function>ob_get_clean</function>
    或 <function>ob_get_flush</function> 将在返回其内容后关闭活跃的缓冲区。
   </simpara>
  </caution>
  <para>
   可以通过调用 <function>ob_clean</function>、<function>ob_end_clean</function>
   或 <function>ob_get_clean</function> 来清理活动缓冲区的内容。
  </para>
  <caution>
   <simpara>
    调用 <function>ob_end_clean</function>
    或 <function>ob_get_clean</function> 将关闭活跃的缓冲区。
   </simpara>
  </caution>
 </section>

 <section>
  <title>关闭缓冲区</title>
  <para>
   可以通过调用 <function>ob_end_clean</function>、<function>ob_end_flush</function>、
   <function>ob_get_flush</function> 或 <function>ob_get_clean</function> 来关闭输出缓冲区。
  </para>
  <warning>
   <simpara>
    没有使用 <constant>PHP_OUTPUT_HANDLER_REMOVABLE</constant> 标志启动的输出缓冲区不能关闭，可能会生成一个
    <constant>E_NOTICE</constant>。
   </simpara>
  </warning>
  <para>
   脚本结束时或调用 <function>exit</function> 时，所有未关闭的输出缓冲区都将被冲刷并关闭。
   缓冲区将按照它们启动的相反顺序被冲刷并关闭。
   最后启动的缓冲区将首先被冲刷，最先启动的缓冲区将最后被冲刷并关闭。
  </para>
  <caution>
   <simpara>
    如果不希望冲刷缓冲区的内容，应该使用自定义的输出处理程序来防止在关闭期间冲刷缓冲区的内容。
   </simpara>
  </caution>
 </section>

 <section xml:id="outcontrol.output-handlers">
  <title>输出处理程序</title>
  <para>
   输出处理程序是与输出缓冲区关联的 <type>callable</type>，通过调用
   <function>ob_clean</function>、<function>ob_flush</function>、<function>ob_end_flush</function>、
   <function>ob_get_flush</function>、<function>ob_end_clean</function>、<function>ob_get_clean</function>
   或 PHP 的关闭过程来调用。
  </para>
  <note>
   <simpara>
    关闭过程将冲刷处理程序的返回值。
   </simpara>
  </note>
  <para>
   如果省略或在启动输出缓冲区时传递 &null;，则将使用内部的
   <literal>"default output handler"</literal>，当调用时返回缓冲区的未修改内容。
   输出处理程序可用于返回缓冲区内容的修改版本和/或具有副作用（例如发送头部）。
  </para>
  <para>
   PHP 自带两个内部输出处理程序：
   <literal>"default output handler"</literal> 和 <literal>"URL-Rewriter"</literal>
   （它集成到自己的输出缓冲区中，最多只能启动两个实例）。
  </para>
  <para>
   捆绑的扩展包括四个额外的输出处理程序：
   <function>mb_output_handler</function>、<function>ob_gzhandler</function>、
   <function>ob_iconv_handler</function>、<function>ob_tidyhandler</function>。
  </para>
 </section>

 <section xml:id="outcontrol.working-with-output-handlers">
  <title>使用输出处理程序</title>
  <para>
   调用输出处理程序时，将缓冲区的内容和一个位掩码传递给输出处理程序。
  </para>
  <para>
   <methodsynopsis>
    <type>string</type>
    <methodname>
     <replaceable>handler</replaceable>
    </methodname>
    <methodparam>
     <type>string</type>
     <parameter>buffer</parameter>
    </methodparam>
    <methodparam choice="opt">
     <type>int</type>
     <parameter>phase</parameter>
    </methodparam>
   </methodsynopsis>
   <variablelist>
    <varlistentry>
     <term><parameter>buffer</parameter></term>
     <listitem>
      <simpara>
       输出缓冲区的内容。
      </simpara>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>phase</parameter></term>
     <listitem>
      <simpara>
       <link linkend="constant.php-output-handler-start">
        <constant>PHP_OUTPUT_HANDLER_<replaceable>*</replaceable></constant>
        常量
       </link> 的位掩码。
      </simpara>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
  <warning>
   <simpara>
    从输出处理程序中调用以下任何函数都会导致致命错误：
    <function>ob_clean</function>、<function>ob_end_clean</function>、
    <function>ob_end_flush</function>、<function>ob_flush</function>、
    <function>ob_get_clean</function>、<function>ob_get_flush</function>、
    <function>ob_start</function>。
   </simpara>
  </warning>
  <note>
   <simpara>
    如果设置了处理程序的 <constant>PHP_OUTPUT_HANDLER_DISABLED</constant>，
    那么调用 <function>ob_end_clean</function>、<function>ob_end_flush</function>、
    <function>ob_get_clean</function>、<function>ob_get_flush</function>、
    <function>ob_clean</function>、<function>ob_flush</function>
    或 PHP 的关闭过程将不会调用处理程序。
    在 PHP 8.4.0 之前，调用 <function>ob_clean</function> 或 <function>ob_flush</function> 时，此标志不起作用。
   </simpara>
  </note>
  <note>
   <simpara>
    脚本的工作目录可能会在某些 Web 服务器（例如 Apache 或内置 Web 服务器）的关闭函数中发生变化。
   </simpara>
  </note>
 </section>

 <section xml:id="outcontrol.flags-passed-to-output-handlers">
  <title>传递给输出处理程序的 flag</title>
  <para>
   传递给输出处理程序的第二个 <parameter>phase</parameter> 参数的位掩码提供了关于处理程序调用的信息。
  </para>
  <note>
   <simpara>
    位掩码可以包含多个标志，应使用按位 <literal>&amp;</literal> 运算符来检查是否设置了标志。
   </simpara>
  </note>
  <warning>
   <simpara>
    <constant>PHP_OUTPUT_HANDLER_WRITE</constant> 和其别名
    <constant>PHP_OUTPUT_HANDLER_CONT</constant> 的值为 <literal>0</literal>，
    因此只能通过使用
    <link linkend="language.operators.comparison">等号运算符</link>
    （<literal>==</literal> 或 <literal>===</literal>）来确定是否设置了它。
   </simpara>
  </warning>
  <para>
   下面的标志在处理程序的生命周期的特定阶段设置：
   <constant>PHP_OUTPUT_HANDLER_START</constant> 在第一次调用处理程序时设置。
   <constant>PHP_OUTPUT_HANDLER_FINAL</constant> 或其别名
   <constant>PHP_OUTPUT_HANDLER_END</constant> 在最后一次调用处理程序时设置，
   即关闭处理程序。此标志也在 PHP 的关闭过程中关闭缓冲区时设置。
  </para>
  <para>
   下面的标志由特定调用处理程序设置：
   <constant>PHP_OUTPUT_HANDLER_FLUSH</constant> 在调用 <function>ob_flush</function> 时设置。
   <constant>PHP_OUTPUT_HANDLER_WRITE</constant> 或其别名
   <constant>PHP_OUTPUT_HANDLER_CONT</constant> 在其内容的大小等于或超过缓冲区的大小时设置，
   并且在缓冲区自动刷新时调用处理程序。
   <constant>PHP_OUTPUT_HANDLER_FLUSH</constant> 在调用 <function>ob_clean</function>、
   <function>ob_end_clean</function> 或 <function>ob_get_clean</function> 时设置。
   当调用 <function>ob_end_clean</function> 或 <function>ob_get_clean</function> 时，
   <constant>PHP_OUTPUT_HANDLER_FINAL</constant> 也会设置。
  </para>
  <note>
   <simpara>
    当调用 <function>ob_end_flush</function> 或 <function>ob_get_flush</function> 时，
    设置 <constant>PHP_OUTPUT_HANDLER_FINAL</constant> 但未设置
    <constant>PHP_OUTPUT_HANDLER_FLUSH</constant>。
   </simpara>
  </note>
 </section>

 <section xml:id="outcontrol.output-handler-return-values">
  <title>输出处理程序的返回值</title>
  <para>
   输出处理程序的返回值在内部转换为字符串，遵循标准 PHP 类型语义，
   但有两个例外：<type>array</type>s 和 <type>bool</type>eans。
  </para>
  <para>
   <type>Array</type>s 被转换为字符串 <literal>"Array"</literal>，
   但不会触发 <literal>Array to string conversion</literal> 警告。
  </para>
  <para>
   如果处理程序返回 &false; 则返回缓冲区的内容。
   如果处理程序返回 &true; 则返回一个空字符串。
  </para>
  <note>
   <simpara>
    如果处理程序返回 &false; 或抛出异常，则设置其
    <constant>PHP_OUTPUT_HANDLER_DISABLED</constant> 状态标志。
   </simpara>
  </note>
 </section>

 <section>
  <title>输出处理程序中抛出异常</title>
  <para>
   如果在输出处理程序中抛出未捕获的异常，则程序将终止，并在关闭过程中调用处理程序后刷新
   <literal>"Uncaught Exception"</literal> 错误消息。
  </para>
  <para>
   如果未捕获的异常是在由 <function>ob_flush</function>、<function>ob_end_flush</function>
   或 <function>ob_get_flush</function> 调用的处理程序中引发的，
   则在错误消息之前刷新缓冲区的内容。
  </para>
  <para>
   如果在关闭过程中的输出处理程序中引发未捕获的异常，则程序终止，而不刷新缓冲区或错误消息。
  </para>
  <note>
   <simpara>
    如果处理程序抛出异常，则设置其
    <constant>PHP_OUTPUT_HANDLER_DISABLED</constant> 状态标志。
   </simpara>
  </note>
 </section>

 <section>
  <title>输出处理程序中引发错误</title>
  <para>
   如果在输出处理程序中引发非致命错误，则程序继续执行。
  </para>
  <para>
   如果非致命错误是在由 <function>ob_flush</function>、<function>ob_end_flush</function>
   或 <function>ob_get_flush</function> 调用的处理程序中引发的，
   则根据处理程序的返回值刷新特定的数据。
   如果处理程序返回 &false; 则刷新缓冲区和错误消息。
   如果返回其他任何值，则刷新处理程序的返回值，但不刷新错误消息。
  </para>
  <note>
   <simpara>
    如果处理程序返回 &false;，则设置其
    <constant>PHP_OUTPUT_HANDLER_DISABLED</constant> 状态标志。
   </simpara>
  </note>
  <para>
   如果输出处理程序中出现致命错误，则程序终止，并在关闭过程中调用处理程序后刷新错误消息。
  </para>
  <para>
   如果致命错误是在由 <function>ob_flush</function>、<function>ob_end_flush</function>
   或 <function>ob_get_flush</function> 调用的处理程序中引发的，
   则在错误消息之前刷新缓冲区的内容。
  </para>
  <para>
   如果在关闭过程中的输出处理程序中引发致命错误，则程序终止，而不刷新缓冲区或错误消息。
  </para>
 </section>

 <section>
  <title>输出处理程序中输出</title>
  <para>
   在特定情况下，处理程序中生成的输出与缓冲区的内容一起刷新。
   此输出不会附加到缓冲区，也不是由 <function>ob_get_flush</function> 返回的字符串的一部分。
  </para>
  <para>
   在冲刷操作（调用 <function>ob_flush</function>、<function>ob_end_flush</function>、
   <function>ob_get_flush</function> 和关闭过程中）期间，
   如果处理程序的返回值为 &false;，则缓冲区的内容将被刷新，然后输出。
   如果处理程序在关闭过程中被调用，则抛出异常或调用 <function>exit</function> 会导致相同的行为。
  </para>
  <note>
   <simpara>
    如果处理程序返回 &false;，则设置其
    <constant>PHP_OUTPUT_HANDLER_DISABLED</constant> 状态标志。
   </simpara>
  </note>
 </section>

 <section>
  <title>输出处理程序状态 flag</title>
  <para>
   每次调用输出处理程序时，缓冲区的 <literal>flags</literal> 位掩码的
   <link linkend="outcontrol.constants.flags-returned-by-handler">处理程序状态标志</link>
   都会被设置，并且是由 <function>ob_get_status</function> 返回的
   <literal>flags</literal> 的一部分。
   如果处理程序成功执行且未返回 &false;，则设置
   <constant>PHP_OUTPUT_HANDLER_STARTED</constant> 和
   <constant>PHP_OUTPUT_HANDLER_PROCESSED</constant>。
   如果处理程序在执行时返回 &false; 或引发异常，则设置
   <constant>PHP_OUTPUT_HANDLER_STARTED</constant> 和
   <constant>PHP_OUTPUT_HANDLER_DISABLED</constant>。
  </para>
  <note>
   <simpara>
    如果处理程序设置了 <constant>PHP_OUTPUT_HANDLER_DISABLED</constant> 标志，
    则不会调用 <function>ob_end_clean</function>、<function>ob_end_flush</function>、
    <function>ob_get_clean</function>、<function>ob_get_flush</function>、
    <function>ob_clean</function>、<function>ob_flush</function>
    或 PHP 的关闭过程。
    在 PHP 8.4.0 之前，调用 <function>ob_clean</function> 或 <function>ob_flush</function> 时，此标志不起作用。
   </simpara>
  </note>
 </section>

</chapter>
<!-- 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
-->