<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 331632 $ -->
<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>callable</type><parameter>output_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 (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;.
       This is the callback signature:
      </para>
      <para>
       <methodsynopsis>
        <type>bool</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 <constant>PHP_OUTPUT_HANDLER_*</constant> constants.
          </simpara>
         </listitem>
        </varlistentry>
       </variablelist>
      </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>. The default
       value <literal>0</literal> means that the output function will only be
       called when the output buffer is closed.
      </para>
      <para>
       Prior to PHP 5.4.0, the value <literal>1</literal> was a special case
       value that set the chunk size to 4096 bytes.
      </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
       <constant>PHP_OUTPUT_HANDLER_CLEANABLE</constant> |
       <constant>PHP_OUTPUT_HANDLER_FLUSHABLE</constant> |
       <constant>PHP_OUTPUT_HANDLER_REMOVABLE</constant>, or
       <constant>PHP_OUTPUT_HANDLER_STDFLAGS</constant> as shorthand.
      </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>,
            <function>ob_end_clean</function>, and
            <function>ob_get_clean</function>.
           </entry>
          </row>
          <row>
           <entry><constant>PHP_OUTPUT_HANDLER_FLUSHABLE</constant></entry>
           <entry>
            <function>ob_end_flush</function>,
            <function>ob_flush</function>, and
            <function>ob_get_flush</function>.
           </entry>
          </row>
          <row>
           <entry><constant>PHP_OUTPUT_HANDLER_REMOVABLE</constant></entry>
           <entry>
            <function>ob_end_clean</function>,
            <function>ob_end_flush</function>, and
            <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="changelog">
  &reftitle.changelog;
  <para>
   <informaltable>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>&Version;</entry>
       <entry>&Description;</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>5.4.0</entry>
       <entry>
        The third parameter of <function>ob_start</function> changed from a
        <type>boolean</type> parameter called <parameter>erase</parameter>
        (which, if set to &false;, would prevent the output buffer from being
        deleted until the script finished executing) to an
        <type>integer</type> parameter called <parameter>flags</parameter>.
        Unfortunately, this results in an API compatibility break for code
        written prior to PHP 5.4.0 that uses the third parameter. See
        <link linkend="function.ob-start.flags-bc">the flags example</link>
        for an example of how to handle this with code that needs to be
        compatible with both.
       </entry>
      </row>
      <row>
       <entry>5.4.0</entry>
       <entry>
        A chunk size of <literal>1</literal> now results in chunks of 1 byte
        being sent to the output buffer.
       </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>

  <para>
   <example xml:id="function.ob-start.flags-bc">
    <title>Creating an uneraseable output buffer in a way compatible with both PHP 5.3 and 5.4</title>
    <programlisting role="php">
<![CDATA[
<?php

if (version_compare(PHP_VERSION, '5.4.0', '>=')) {
  ob_start(null, 0, PHP_OUTPUT_HANDLER_STDFLAGS ^
    PHP_OUTPUT_HANDLER_REMOVABLE);
} else {
  ob_start(null, 0, false);
}

?>
]]>
    </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
-->