ob-start.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: da6be21fef84d61cc4c621b3fe1d5fd2c9046c45 Maintainer: avenger Status: ready -->
<!-- CREDITS: mowangjuanzi, Luffy -->
<refentry xml:id="function.ob-start" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>ob_start</refname>
  <refpurpose>打开输出控制缓冲</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>bool</type><methodname>ob_start</methodname>
   <methodparam choice="opt"><type class="union"><type>callable</type><type>null</type></type><parameter>callback</parameter><initializer>&null;</initializer></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>chunk_size</parameter><initializer>0</initializer></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>flags</parameter><initializer><constant>PHP_OUTPUT_HANDLER_STDFLAGS</constant></initializer></methodparam>
  </methodsynopsis>
  <para>
   此函数将打开输出缓冲。当输出缓冲激活后，脚本将不会输出内容，相反需要输出的内容被存储在内部缓冲区中。参阅<xref
   linkend="outcontrol.what-output-is-buffered"/>以了解哪些输出受到影响。
  </para>
  <para>
   输出缓冲区是可堆叠的，也就是说，当一个缓冲区处于活动状态时也可以调用
   <function>ob_start</function>。如果有多重输出缓冲区是活跃的，输出内容会一直按嵌套的顺序依次过滤。参阅<xref
   linkend="outcontrol.nesting-output-buffers"/>获取更多详情。
  </para>
  <para>
   有关输出缓冲区的详细信息，请参阅<xref linkend="outcontrol.user-level-output-buffers"/>
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>callback</parameter></term>
     <listitem>
      <para>
       可以指定可选的 <parameter>callback</parameter> <type>callable</type>。也可以通过传递 &null; 来绕过它。
      </para>
      <para>
       当冲刷（发送）、清理输出缓冲区或在脚本末尾冲刷输出缓冲区时，将调用 <parameter>callback</parameter>。
      </para>
      <para>
       <parameter>callback</parameter> 的签名如下：
      </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="outcontrol.constants"><constant>PHP_OUTPUT_HANDLER_*</constant> 常量</link>。<link
           linkend="constant.php-output-handler-start"><constant>PHP_OUTPUT_HANDLER_<replaceable>*</replaceable></constant>
           常量</link>的位掩码。有关更多详细信息，请参阅<xref linkend="outcontrol.flags-passed-to-output-handlers"/>。
          </simpara>
         </listitem>
        </varlistentry>
       </variablelist>
      </para>
      <para>
       如果 <parameter>callback</parameter> 返回 &false;，则返回缓冲区的内容。有关更多详细信息，请参阅 <xref linkend="outcontrol.output-handler-return-values"/>。
      </para>
      <warning>
       <simpara>
        从输出处理程序中调用以下任何函数都将导致 fatal 错误 
        <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>
      <para>
       有关 <parameter>callback</parameter>（输出处理程序）的更多详细信息，请参阅<xref linkend="outcontrol.output-handlers"/>和<xref linkend="outcontrol.working-with-output-handlers"/>。
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>chunk_size</parameter></term>
     <listitem>
      <para>
       如果传递了可选参数 chunk_size，则在任何导致缓冲区长度等于或大于 <parameter>chunk_size</parameter>
       的代码块的输出之后，都会冲刷缓冲区。默认值 <literal>0</literal>
       表示缓冲所有输出，直到缓冲区关闭。更多详细信息，请参阅<xref linkend="outcontrol.buffer-size"/>。
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>flags</parameter></term>
     <listitem>
      <para>
       <parameter>flags</parameter>
       参数是位掩码，用于控制可以在输出缓冲区上执行的操作。默认是允许清理、冲刷和移除输出缓冲区，可以通过<link
       linkend="outcontrol.constants.buffer-control-flags">缓冲区控制 flag</link>手动设置。参阅<xref
       linkend="outcontrol.operations-on-buffers"/>获取更多详细信息。
      </para>
      <para>
       每个标志都控制着对一组功能的访问，详细介绍如下：
       <informaltable>
        <tgroup cols="2">
         <thead>
          <row>
           <entry>常量</entry>
           <entry>函数</entry>
          </row>
         </thead>
         <tbody>
          <row>
           <entry><constant>PHP_OUTPUT_HANDLER_CLEANABLE</constant></entry>
           <entry>
            <function>ob_clean</function>
           </entry>
          </row>
          <row>
           <entry><constant>PHP_OUTPUT_HANDLER_FLUSHABLE</constant></entry>
           <entry>
            <function>ob_flush</function>
           </entry>
          </row>
          <row>
           <entry><constant>PHP_OUTPUT_HANDLER_REMOVABLE</constant></entry>
           <entry>
            <function>ob_end_clean</function>、<function>ob_end_flush</function>、<function>ob_get_clean</function>、<function>ob_get_flush</function>
           </entry>
          </row>
         </tbody>
        </tgroup>
       </informaltable>
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   &return.success;
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>用户自定义回调函数的示例</title>
    <programlisting role="php">
<![CDATA[
<?php

function callback($buffer)
{
  // replace all the apples with oranges
  return (str_replace("apples", "oranges", $buffer));
}

ob_start("callback");

?>
<html>
<body>
<p>It's like comparing apples to oranges.</p>
</body>
</html>
<?php

ob_end_flush();

?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
<html>
<body>
<p>It's like comparing oranges to oranges.</p>
</body>
</html>
]]>
    </screen>
   </example>
  </para>

 <para>
   <example xml:id="function.ob-start.flags-bc">
    <title>创建不可擦除的输出缓冲区</title>
    <programlisting role="php">
<![CDATA[
<?php

ob_start(null, 0, PHP_OUTPUT_HANDLER_STDFLAGS ^ PHP_OUTPUT_HANDLER_REMOVABLE);

?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>ob_get_contents</function></member>
    <member><function>ob_end_clean</function></member>
    <member><function>ob_end_flush</function></member>
    <member><function>ob_implicit_flush</function></member>
    <member><function>ob_gzhandler</function></member>
    <member><function>ob_iconv_handler</function></member>
    <member><function>mb_output_handler</function></member>
    <member><function>ob_tidyhandler</function></member>
   </simplelist>
  </para>
 </refsect1>

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