<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="function.ob-start" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>ob_start</refname>
  <refpurpose>Turn on output buffering</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>
   This function will turn output buffering on.
   While output buffering is active no output is sent from the script,
   instead the output is stored in an internal buffer.
   See <xref linkend="outcontrol.what-output-is-buffered"/>
   on exactly what output is affected.
  </para>
  <para>
   Output buffers are stackable, that is,
   <function>ob_start</function> may be called while another buffer is active.
   If multiple output buffers are active,
   output is being filtered sequentially
   through each of them in nesting order.
   See <xref linkend="outcontrol.nesting-output-buffers"/> for more details.
  </para>
  <para>
   See <xref linkend="outcontrol.user-level-output-buffers"/>
   for a detailed description of output buffers.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>callback</parameter></term>
     <listitem>
      <para>
       An optional <parameter>callback</parameter> <type>callable</type> may be
       specified. It can also be bypassed by passing &null;.
      </para>
      <para>
       <parameter>callback</parameter> is invoked when the output buffer is
       flushed (sent), cleaned, or when the output buffer is flushed
       at the end of the script.
      </para>
      <para>
       The signature of the <parameter>callback</parameter> is as follows:
      </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>
           Contents of the output buffer.
          </simpara>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>phase</parameter></term>
         <listitem>
          <simpara>
           Bitmask of
           <link linkend="constant.php-output-handler-start">
            <constant>PHP_OUTPUT_HANDLER_<replaceable>*</replaceable></constant>
            constants
           </link>.
           See <xref linkend="outcontrol.flags-passed-to-output-handlers"/>
           for more details.
          </simpara>
         </listitem>
        </varlistentry>
       </variablelist>
      </para>
      <para>
       If <parameter>callback</parameter> returns &false;
       the contents of the buffer are returned.
       See <xref linkend="outcontrol.output-handler-return-values"/>
       for more details.
      </para>
      <warning>
       <simpara>
        Calling any of the following functions from within an output handler
        will result in a fatal error:
        <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>
       See <xref linkend="outcontrol.output-handlers"/>
       and <xref linkend="outcontrol.working-with-output-handlers"/>
       for more details on <parameter>callback</parameter>s (output handlers).
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>chunk_size</parameter></term>
     <listitem>
      <para>
       If the optional parameter <parameter>chunk_size</parameter> is passed,
       the buffer will be flushed after any block of code resulting in output
       that causes the buffer's length to equal
       or exceed <parameter>chunk_size</parameter>.
       The default value <literal>0</literal> means
       that all output is buffered until the buffer is turned off.
       See <xref linkend="outcontrol.buffer-size"/> for more details.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>flags</parameter></term>
     <listitem>
      <para>
       The <parameter>flags</parameter> parameter is a bitmask that controls
       the operations that can be performed on the output buffer. The default
       is to allow output buffers to be cleaned, flushed and removed, which
       can be set explicitly via the
       <link linkend="outcontrol.constants.buffer-control-flags">
        buffer control flags
       </link>.
       See <xref linkend="outcontrol.operations-on-buffers"/>
       for more details.
      </para>
      <para>
       Each flag controls access to a set of functions, as described below:
       <informaltable>
        <tgroup cols="2">
         <thead>
          <row>
           <entry>Constant</entry>
           <entry>Functions</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>User defined callback function example</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>Creating an unerasable output buffer</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
-->