<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 297626 $ -->
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.ob-start">
 <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>callback</type><parameter>output_callback</parameter></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>chunk_size</parameter></methodparam>
   <methodparam choice="opt"><type>bool</type><parameter>erase</parameter></methodparam>
  </methodsynopsis>
  <para>
   This function will turn output buffering on. While output buffering is
   active no output is sent from the script (other than headers), instead the
   output is stored in an internal buffer.
  </para>
  <para>
   The contents of this internal buffer may be copied into a string variable
   using <function>ob_get_contents</function>.  To output what is stored in
   the internal buffer, use <function>ob_end_flush</function>. Alternatively,
   <function>ob_end_clean</function> will silently discard the buffer
   contents.
  </para>
  <warning>
   <para>
    Some web servers (e.g. Apache) change the working directory of a script
    when calling the callback function. You can change it back by e.g.
    <literal>chdir(dirname($_SERVER['SCRIPT_FILENAME']))</literal> in the
    callback function.
   </para>
  </warning>
  <para>
   Output buffers are stackable, that is, you may call
   <function>ob_start</function> while another
   <function>ob_start</function> is active. Just make
   sure that you call <function>ob_end_flush</function>
   the appropriate number of times. If multiple output callback
   functions are active, output is being filtered sequentially
   through each of them in nesting order.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>output_callback</parameter></term>
     <listitem>
      <para>
       An optional <parameter>output_callback</parameter> function may be
       specified. This function takes a string as a parameter and should
       return a string. The function will be called when
       the output buffer is flushed (sent) or cleaned (with
       <function>ob_flush</function>, <function>ob_clean</function> or similar
       function) or when the output buffer
       is flushed to the browser at the end of the request.  When
       <parameter>output_callback</parameter> is called, it will receive the
       contents of the output buffer as its parameter and is expected to
       return a new output buffer as a result, which will be sent to the
       browser. If the <parameter>output_callback</parameter> is not a
       callable function, this function will return &false;.
      </para>
      <para>
       If the callback function has two parameters, the second parameter is
       filled with a bit-field consisting of
       <constant>PHP_OUTPUT_HANDLER_START</constant>,
       <constant>PHP_OUTPUT_HANDLER_CONT</constant> and
       <constant>PHP_OUTPUT_HANDLER_END</constant>.
      </para>
      <para>
       If <parameter>output_callback</parameter> returns &false; original
       input is sent to the browser.
      </para>
      <para>
       The <parameter>output_callback</parameter> parameter may be bypassed
       by passing a &null; value.
      </para>
      <para>
       <function>ob_end_clean</function>, <function>ob_end_flush</function>,
       <function>ob_clean</function>, <function>ob_flush</function> and
       <function>ob_start</function> may not be called from a callback
       function. If you call them from callback function, the behavior is
       undefined. If you would like to delete the contents of a buffer,
       return "" (a null string) from callback function.
       You can't even call functions using the output buffering functions like
       <literal>print_r($expression, true)</literal> or
       <literal>highlight_file($filename, true)</literal> from a callback
       function.
      </para>
      <note>
       <para>
        In PHP 4.0.4, <function>ob_gzhandler</function> was introduced to
        facilitate sending gz-encoded data to web browsers that support
        compressed web pages.  <function>ob_gzhandler</function> determines
        what type of content encoding the browser will accept and will return
        its output accordingly.
       </para>
      </note>
     </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 output call which causes the buffer's
       length to equal or exceed <parameter>chunk_size</parameter>.
       Default value 0 means that the function is called only in the end,
       other special value 1 sets <parameter>chunk_size</parameter> to 4096.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>erase</parameter></term>
     <listitem>
      <para>
       If the optional parameter <parameter>erase</parameter> is set to &false;,
       the buffer will not be deleted until the script finishes.
       This causes that flushing and cleaning functions would issue a notice
       and return &false; if called.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

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

 <refsect1 role="changelog">
  &reftitle.changelog;
  <para>
   <informaltable>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>&Version;</entry>
       <entry>&Description;</entry>
      </row>
     </thead>
     <tbody>
      <!-- FIXME PHP_6
      <row>
       <entry>6.0.0</entry>
       <entry>
        Value 1 is no more special.
       </entry>
      </row>
      -->
      <row>
       <entry>4.3.2</entry>
       <entry>
        This function was changed to return &false; in case the passed
        <parameter>output_callback</parameter> can not be executed.
       </entry>
      </row>
      <row>
       <entry>4.2.0</entry>
       <entry>
        Added the <parameter>erase</parameter> parameter.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </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>
 </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
-->