<?xml version="1.0" encoding="utf-8"?>
<chapter xml:id="outcontrol.user-level-output-buffers" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude">
 <title>User-Level Output Buffers</title>
 <para>
  User-level output buffers can be started, manipulated
  and terminated from PHP code.
  Each of these buffers includes an output buffer
  and an associated output handler function.
 </para>

 <section xml:id="outcontrol.what-output-is-buffered">
  <title>What Output Is Buffered?</title>
  <para>
   PHP's user-level output buffers buffer all output after they are started
   until they are turned off or the script ends.
   Output in the context of PHP's user-level output buffer
   is everything that PHP would display or send back to the browser.
   In practical terms, output is non-zero length data that is:
   <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>
    Data that is written directly to <literal>stdout</literal>
    or passed to an SAPI function with a similar functionality
    will not be captured by user-level output buffers.
    This includes
    writing data to <literal>stdout</literal> with <function>fwrite</function>
    or sending headers using <function>header</function>
    or <function>setcookie</function>.
   </simpara>
  </note>
 </section>

 <section>
  <title>Turning Output Buffering On</title>
  <para>
   Output buffering can be turned on by using
   the <function>ob_start</function> function or by setting
   the <link linkend="ini.output-buffering">output_buffering</link>
   and <link linkend="ini.output-handler">output_handler</link>
   &php.ini; settings.
   While both can create output buffers,
   <function>ob_start</function> is more flexible
   as it accepts user-defined functions as output handlers
   and the operations allowed on the buffer (flush, clean, remove)
   can be set as well.
   Buffers started with <function>ob_start</function> will be active
   from the line the function was called,
   while those started with
   <link linkend="ini.output-buffering">output_buffering</link>
   will be buffering output from the first line of the script.
  </para>
  <para>
   PHP is also shipped with a built-in <literal>"URL-Rewriter"</literal>
   output handler which starts its own output buffer and only allows
   up to two instances of it running at any time
   (one for user-level URL-rewriting
   and one for transparent session id support).
   These buffers can be started by calling
   the <function>output_add_rewrite_var</function> function
   and/or by enabling the
   <link linkend="ini.session.use-trans-sid">session.use_trans_sid</link>
   &php.ini; setting.
  </para>
  <para>
   The bundled <literal>zlib</literal> extension has its own
   output buffer which can be enabled by using the
   <link linkend="ini.zlib.output-compression">zlib.output_compression</link>
   &php.ini; setting.
  </para>
  <note>
   <simpara>
    While <literal>"URL-Rewriter"</literal> is special
    in that it only allows up to two instances of it running at any one time,
    all user-level output buffers use the same underlying buffers
    used by <function>ob_start</function>
    with their functionality implemented by a custom output handler function.
    As such, all of their functionality can be emulated by userland code.
   </simpara>
  </note>
 </section>

 <section xml:id="outcontrol.nesting-output-buffers">
  <title>Nesting Output Buffers</title>
  <para>
   If there is an output buffer active when a new buffer is started,
   the new buffer will be nested inside the previously active buffer.
   The inner buffer will behave the same way regardless whether it is nested
   but output buffered by it will not be buffered by the outer buffer.
   Only output flushed by the inner buffer will be buffered by the outer buffer.
  </para>
  <para>
   Most <literal>ob_<replaceable>*</replaceable></literal> functions only work
   with the active output buffer (the last one started)
   therefore only the active buffer can be flushed, cleaned and turned off.
   The functions that work with other buffers are
   <function>ob_list_handlers</function>
   which returns the list of all output handlers in use
   and <function>ob_get_status</function>
   which can return information on the active buffer only
   or on all buffers in use.
  </para>
  <para>
   Calling <function>ob_get_level</function>
   or <function>ob_get_status</function> will return
   the nesting level of the active output buffer.
  </para>
  <caution>
   <simpara>
    The value for identical levels between <function>ob_get_level</function>
    and <function>ob_get_status</function> is off by one.
    For <function>ob_get_level</function>
    the first level is <literal>1</literal>,
    whereas for <function>ob_get_status</function>
    the first level is <literal>0</literal>.
   </simpara>
  </caution>
 </section>

 <section xml:id="outcontrol.buffer-size">
  <title>Buffer Size</title>
  <para>
   Buffer sizes are expressed by integers
   and represent the number of bytes the buffer can store without flushing.
   When the size of output in the buffer exceeds the size of the buffer,
   the contents of the buffer are sent to the output handler,
   its return value is flushed and the buffer is cleared.
  </para>
  <para>
   With the exception of <literal>"URL-Rewriter"</literal>,
   the size of output buffers can be set when the buffer is started.
   If set to <literal>0</literal>,
   the output buffer is only limited by the memory available to PHP.
   If set to <literal>1</literal>,
   the buffer is flushed after every block of code producing
   any non-zero length output.
  </para>
  <para>
   The size of output buffers can be retrieved by calling
   <function>ob_get_status</function>.
  </para>
  <para>
   Output buffers started with <function>ob_start</function>
   will have their buffer sizes set to the integer value passed to
   the function's second <parameter>chunk_size</parameter> parameter.
   If omitted, it is set to <literal>0</literal>.
  </para>
  <para>
   The output buffer started with
   <link linkend="ini.output-buffering">output_buffering</link>
   set to <literal>"On"</literal> will have its buffer size set to 0.
   If set to an integer than buffer size will correspond to that number.
  </para>
  <para>
   <literal>"URL-Rewriter"</literal>'s buffer size is set to <literal>0</literal>,
   therefore it is only limited by the memory available to PHP.
  </para>
  <para>
   The size of <literal>zlib</literal>'s output buffer is controlled by the
   <link linkend="ini.zlib.output-compression">zlib.output_compression</link>
   &php.ini; setting.
   If set to <literal>"On"</literal> the buffer size will be
   <literal>"16K"</literal>/<literal>16384</literal>.
   If set to an integer then buffer size will correspond to that number in bytes.
  </para>
 </section>

 <section xml:id="outcontrol.operations-on-buffers">
  <title>Operations Allowed On Buffers</title>
  <para>
   The operations allowed on buffers can be controlled
   by passing one of the
   <link linkend="outcontrol.constants.buffer-control-flags">buffer control flags</link>
   to <function>ob_start</function>'s third
   <parameter>flags</parameter> parameter.
   If omitted, all operations are allowed by default.
   If <literal>0</literal> is used instead,
   the buffer cannot be flushed, cleaned or removed
   but it's contents can still be retrieved.
  </para>
  <para>
   <constant>PHP_OUTPUT_HANDLER_CLEANABLE</constant> allows
   <function>ob_clean</function> to clean the contents of the buffer.
  </para>
  <warning>
   <simpara>
    The absence of the <constant>PHP_OUTPUT_HANDLER_CLEANABLE</constant> flag
    will not prevent <function>ob_end_clean</function>
    or <function>ob_get_clean</function> from clearing the contents of the buffer.
   </simpara>
  </warning>
  <para>
   <constant>PHP_OUTPUT_HANDLER_FLUSHABLE</constant> allows
   <function>ob_flush</function> to flush the contents of the buffer.
  </para>
  <warning>
   <simpara>
    The absence of the <constant>PHP_OUTPUT_HANDLER_FLUSHABLE</constant> flag
    will not prevent <function>ob_end_flush</function>
    or <function>ob_get_flush</function> from flushing the contents of the buffer.
   </simpara>
  </warning>
  <para>
   <constant>PHP_OUTPUT_HANDLER_REMOVABLE</constant> allows
   <function>ob_end_clean</function>, <function>ob_end_flush</function>,
   <function>ob_get_clean</function> or <function>ob_get_flush</function>
   to turn off the buffer.
  </para>
  <para>
   <constant>PHP_OUTPUT_HANDLER_STDFLAGS</constant>,
   the combination of the three flags will allow each of the three operations
   to be performed on the buffer.
  </para>
 </section>

 <section>
  <title>Flushing, Accessing And Cleaning Buffer Contents</title>
  <para>
   Flushing sends and discards the contents of the active buffer.
   Output buffers get flushed when the size of the output
   exceeds the size of the buffer; the script ends or
   <function>ob_flush</function>, <function>ob_end_flush</function>
   or <function>ob_get_flush</function> is called.
  </para>
  <caution>
   <simpara>
    Calling <function>ob_end_flush</function>
    or <function>ob_get_flush</function> will turn off the active buffer.
   </simpara>
  </caution>
  <caution>
   <simpara>
    Flushing buffers will flush the return value of the output handler
    which can differ from the contents of the buffer.
    For example, using <function>ob_gzhandler</function> will compress
    the output and flush the compressed output.
   </simpara>
  </caution>
  <para>
   The contents of the active buffer can be retrieved by calling
   <function>ob_get_contents</function>, <function>ob_get_clean</function>
   or <function>ob_get_flush</function>.
  </para>
  <para>
   If only the length of the buffer's contents are needed,
   <function>ob_get_length</function> or <function>ob_get_status</function>
   will return the length of the contents in bytes.
  </para>
  <caution>
   <simpara>
    Calling <function>ob_get_clean</function>
    or <function>ob_get_flush</function> will turn off the active buffer
    after returning the its contents.
   </simpara>
  </caution>
  <para>
   The contents of the active buffer can be cleaned by calling
   <function>ob_clean</function>, <function>ob_end_clean</function>
   or <function>ob_get_clean</function>.
  </para>
  <caution>
   <simpara>
    Calling <function>ob_end_clean</function>
    or <function>ob_get_clean</function> will turn off the active buffer.
   </simpara>
  </caution>
 </section>

 <section>
  <title>Turning Buffers Off</title>
  <para>
   Output buffers can be turned off by calling
   <function>ob_end_clean</function>, <function>ob_end_flush</function>,
   <function>ob_get_flush</function> or <function>ob_get_clean</function>.
  </para>
  <warning>
   <simpara>
    Output buffers started without the
    <constant>PHP_OUTPUT_HANDLER_REMOVABLE</constant> flag
    cannot be turned off and may generate an <constant>E_NOTICE</constant>.
   </simpara>
  </warning>
  <para>
   Every output buffer that has not been closed by the end of the script
   or when <function>exit</function> is called will be flushed
   and turned off by PHP's shutdown process.
   The buffers will be flushed and turned off in reverse order
   of their starting up.
   The last buffered started will be first,
   the first buffer started will be last to be flushed and turned off.
  </para>
  <caution>
   <simpara>
    If flushing of the buffer's contents is not desired,
    a custom output handler should be used to prevent flushing during shutdown.
   </simpara>
  </caution>
 </section>

 <section xml:id="outcontrol.output-handlers">
  <title>Output Handlers</title>
  <para>
   Output handlers are <type>callable</type>s associated with output buffers
   that are invoked by calling <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> or during PHP's shutdown process.
  </para>
  <note>
   <simpara>
    The shutdown process will flush the return value of the handler.
   </simpara>
  </note>
  <para>
   If omitted or &null; when starting the output buffer
   the internal <literal>"default output handler"</literal> will be used
   which returns the unmodified contents of the buffer when invoked.
   Output handlers can be used to return a modified version
   of the buffer's contents and/or have side-effects (e.g. send headers).
  </para>
  <para>
   PHP comes with two internal output handlers:
   <literal>"default output handler"</literal>
   and <literal>"URL-Rewriter"</literal> (which is integrated into
   its own output buffer and only up to two instances of it can be started).
  </para>
  <para>
   The bundled extensions include four additional output handlers:
   <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>Working With Output Handlers</title>
  <para>
   When invoked, output handlers are passed the contents of the buffer
   and a bitmask indicating the status of output buffering.
  </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>.
      </simpara>
     </listitem>
    </varlistentry>
   </variablelist>
  </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>
  <note>
   <simpara>
    If the <constant>PHP_OUTPUT_HANDLER_DISABLED</constant> of a handler is set,
    the handler will not be invoked by calling
    <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>
    or during PHP's shutdown process.
    Prior to PHP 8.4.0, this flag had no effect when calling <function>ob_clean</function>
    or <function>ob_flush</function>.
   </simpara>
  </note>
  <note>
   <simpara>
    The working directory of the script can change inside the shutdown function
    under some web servers, e.g. Apache or the built-in web server.
   </simpara>
  </note>
 </section>

 <section xml:id="outcontrol.flags-passed-to-output-handlers">
  <title>Flags Passed To Output Handlers</title>
  <para>
   The bitmask passed to the second <parameter>phase</parameter> parameter
   of the output handler provides information on the invocation of the handler.
  </para>
  <note>
   <simpara>
    The bitmask can include more than one flag
    and the bitwise <literal>&amp;</literal> operator should be used
    to check whether a flag is set.
   </simpara>
  </note>
  <warning>
   <simpara>
    The value of <constant>PHP_OUTPUT_HANDLER_WRITE</constant> and its alias
    <constant>PHP_OUTPUT_HANDLER_CONT</constant> is <literal>0</literal>
    therefore whether it is set can only be determined
    by using an
    <link linkend="language.operators.comparison">equality operator</link>
    (<literal>==</literal> or <literal>===</literal>).
   </simpara>
  </warning>
  <para>
   The following flags are set in a specific phase of the handler's lifecycle:
   <constant>PHP_OUTPUT_HANDLER_START</constant> is set
   when a handler is invoked for the first time.
   <constant>PHP_OUTPUT_HANDLER_FINAL</constant>
   or its alias <constant>PHP_OUTPUT_HANDLER_END</constant>
   is set when a handler is invoked for the last time,
   i.e. it is being turned off. This flag is also set
   when buffers are being turned off by PHP's shutdown process.
  </para>
  <para>
   The following flags are set by a specific invocation of the handler:
   <constant>PHP_OUTPUT_HANDLER_FLUSH</constant> is set
   when the handler is invoked by calling <function>ob_flush</function>.
   <constant>PHP_OUTPUT_HANDLER_WRITE</constant>
   or its alias <constant>PHP_OUTPUT_HANDLER_CONT</constant>
   is set when the size of its contents equals or exceeds the size of the buffer
   and the handler is invoked while the buffer is being automatically flushed.
   <constant>PHP_OUTPUT_HANDLER_FLUSH</constant> is set
   when the handler is invoked by calling <function>ob_clean</function>,
   <function>ob_end_clean</function> or <function>ob_get_clean</function>.
   When <function>ob_end_clean</function> or <function>ob_get_clean</function>
   is called, <constant>PHP_OUTPUT_HANDLER_FINAL</constant> is set as well.
  </para>
  <note>
   <simpara>
    When <function>ob_end_flush</function> or <function>ob_get_flush</function>
    is called, <constant>PHP_OUTPUT_HANDLER_FINAL</constant> is set
    but <constant>PHP_OUTPUT_HANDLER_FLUSH</constant> is not.
   </simpara>
  </note>
 </section>

 <section xml:id="outcontrol.output-handler-return-values">
  <title>Output Handler Return Values</title>
  <para>
   The return value of the output handler is internally coerced into a string
   following standard PHP type semantics, with two exceptions:
   <type>array</type>s and <type>bool</type>eans.
  </para>
  <para>
   Arrays are converted into the string <literal>"Array"</literal>
   but the <literal>Array to string conversion</literal> warning
   is not triggered.
  </para>
  <para>
   If the handler returns &false; the contents of the buffer are returned.
   If the handler returns &true; an empty string is returned.
  </para>
  <note>
   <simpara>
    If a handler returns &false; or throws an exception
    its <constant>PHP_OUTPUT_HANDLER_DISABLED</constant> status flag is set.
   </simpara>
  </note>
 </section>

 <section>
  <title>Exceptions Thrown In Output Handlers</title>
  <para>
   If an uncaught exception is thrown in an output handler
   the program terminates and the handler is invoked
   by the shutdown process after which
   the <literal>"Uncaught Exception"</literal> error message is flushed.
  </para>
  <para>
   If the uncaught exception is thrown in a handler
   invoked by <function>ob_flush</function>,
   <function>ob_end_flush</function> or <function>ob_get_flush</function>,
   the contents of the buffer are flushed before the error message.
  </para>
  <para>
   If an uncaught exception is thrown in an output handler during shutdown,
   the handler is terminated and neither the contents of the buffer
   nor the error message is flushed.
  </para>
  <note>
   <simpara>
    If a handler throws an exception
    its <constant>PHP_OUTPUT_HANDLER_DISABLED</constant> status flag is set.
   </simpara>
  </note>
 </section>

 <section>
  <title>Errors Raised In Output Handlers</title>
  <para>
   If a non-fatal error is raised in an output handler
   the program continues execution.
  </para>
  <para>
   If the non-fatal error is raised in a handler invoked by
   <function>ob_flush</function>, <function>ob_end_flush</function>
   or <function>ob_get_flush</function>,
   the buffer flushes certain data depending on the return value of the handler.
   If the handler returns &false; the buffer and the error message are flushed.
   If the returns anything else the handler return value is flushed
   but not the error message.
  </para>
  <note>
   <simpara>
    If a handler returns &false;
    its <constant>PHP_OUTPUT_HANDLER_DISABLED</constant> status flag is set.
   </simpara>
  </note>
  <para>
   If a fatal error is raised in an output handler
   the program terminates and the handler is invoked
   by the shutdown process after which the error message is flushed.
  </para>
  <para>
   If the fatal error is raised in a handler
   invoked by <function>ob_flush</function>,
   <function>ob_end_flush</function> or <function>ob_get_flush</function>,
   the contents of the buffers are flushed before the error message.
  </para>
  <para>
   If a fatal error is raised in an output handler during shutdown
   the program terminates without flushing the buffer or the error message.
  </para>
 </section>

 <section>
  <title>Output In Output Handlers</title>
  <para>
   In specific circumstances, output produced in the handler is flushed
   along with the contents of the buffer.
   This output is not appended to the buffer and is not part of the string
   returned by <function>ob_get_flush</function>.
  </para>
  <para>
   During flush operations (calling <function>ob_flush</function>,
   <function>ob_end_flush</function>, <function>ob_get_flush</function>
   and during shutdown)
   if the return value of a handler is &false;
   the contents of the buffer are flushed followed by the output.
   If the handler is not invoked during shutdown
   the handler throwing an exception or <function>exit</function> being called
   results in the same behavior.
  </para>
  <note>
   <simpara>
    If a handler returns &false;
    its <constant>PHP_OUTPUT_HANDLER_DISABLED</constant> status flag is set.
   </simpara>
  </note>
 </section>

 <section>
  <title>Output Handler Status Flags</title>
  <para>
   The
   <link linkend="outcontrol.constants.flags-returned-by-handler">
    handler status flags
   </link> of the buffer's <literal>flags</literal> bitmask
   are set every time to the output handler is invoked
   and are part of the <literal>flags</literal> returned by
   <function>ob_get_status</function>.
   If the handler successfully executes and does not return &false;,
   <constant>PHP_OUTPUT_HANDLER_STARTED</constant> and
   <constant>PHP_OUTPUT_HANDLER_PROCESSED</constant> is set.
   If the handler returns &false; or throws an exception while executing,
   <constant>PHP_OUTPUT_HANDLER_STARTED</constant> and
   <constant>PHP_OUTPUT_HANDLER_DISABLED</constant> is set.
  </para>
  <note>
   <simpara>
    If the <constant>PHP_OUTPUT_HANDLER_DISABLED</constant> of a handler is set,
    the handler will not be invoked by calling
    <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>
    or during PHP's shutdown process.
    Prior to PHP 8.4.0, this flag had no effect when calling <function>ob_clean</function>
    or <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
-->