<?xml version="1.0" encoding="utf-8"?>
 <reference id="ref.outcontrol">
  <title>Output Control Functions</title>
  <titleabbrev>Output Control</titleabbrev>

  <partintro>
   <para>
    The Output Control functions allow you to control when output is
    sent from the script.  This can be useful in several different
    situations, especially if you need to send headers to the browser
    after your script has began outputing data.  The Output Control
    functions do not affect headers sent using
    <function>header</function> or <function>setcookie</function>,
    only functions such as <function>echo</function> and data between
    blocks of PHP code.
   </para>
   <para>
    <example>
     <title>Output Control example</title>
     <programlisting role="php">
&lt;?php

ob_start();
echo "Hello\n";

setcookie ("cookiename", "cookiedata");

ob_end_flush();

?&gt;
     </programlisting>
    </example>
   </para>
   <para>
    In the above example, the output from <function>echo</function>
    would be stored in the output buffer until
    <function>ob_end_flush</function> was called.  In the mean time,
    the call to <function>setcookie</function> successfully stored a
    cookie without causing an error. (You can not normally send
    headers to the browser after data has already been sent.)
   </para>
   <para>
    See also <function>header</function> and
    <function>setcookie</function>.
   </para>
  </partintro>

  <refentry id="function.flush">
   <refnamediv>
    <refname>flush</refname> 
    <refpurpose>Flush the output buffer</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>void</type><methodname>flush</methodname>
      <void/>
     </methodsynopsis>
    <simpara>
     Flushes the output buffers of PHP and whatever backend PHP is
     using (CGI, a web server, etc.)  This effectively tries to push
     all the output so far to the user's browser.
    </simpara>
		<note>
		 <para>
			<function>flush</function> has no effect on the buffering
			 scheme of your webserver or the browser on the client
			 side. 
		 </para>
		 <para>
			Several servers, especially on Win32, will still buffer
			the output from your script until it terminates before
			transmitting the results to the browser. 
		 </para>
		 <para>
			Even the browser may buffer its input before displaying it. 
			Netscape, for example, buffers text until it receives an
			end-of-line or the beginning of a tag, and it won't render
			tables until the &lt;/table&gt; tag of the outermost table is
			seen.
		 </para>
		</note>
   </refsect1>
  </refentry>

  <refentry id="function.ob-start">
   <refnamediv>
    <refname>ob_start</refname> 
    <refpurpose>Turn on output buffering</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>void</type><methodname>ob_start</methodname>
      <methodparam choice="opt"><type>string</type><parameter>
        output_callback
       </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>
    <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
     <function>ob_end_flush</function> is called, 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.
    </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 it's output accordingly.
     </para>
    </note>
    <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>
    <example>
     <title>User defined callback function example</title>
     <programlisting role="php">
&lt;?php

function callback($buffer) {

  // replace all the apples with oranges
  return (ereg_replace("apples", "oranges", $buffer));

}

ob_start("callback");

?&gt;

&lt;html&gt;
&lt;body&gt;
&lt;p&gt;It's like comparing apples to oranges.
&lt;/body&gt;
&lt;/html&gt;

&lt;?php

ob_end_flush();

?&gt;
     </programlisting>
    </example>
    <para>
     Would produce:
     <informalexample>
      <programlisting role="php">
&lt;html&gt;
&lt;body&gt;
&lt;p&gt;It's like comparing oranges to oranges.
&lt;/body&gt;
&lt;/html&gt;
      </programlisting>
     </informalexample>
    </para>
    <para>
     See also <function>ob_get_contents</function>,
     <function>ob_end_flush</function>,
     <function>ob_end_clean</function>,
     <function>ob_implicit_flush</function> and
     <function>ob_gzhandler</function>.
    </para>
   </refsect1>
  </refentry>
 
  <refentry id="function.ob-get-contents">
   <refnamediv>
    <refname>ob_get_contents</refname> 
    <refpurpose>
     Return the contents of the output buffer
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>ob_get_contents</methodname>
      <void/>
     </methodsynopsis>
    <para>
     This will return the contents of the output buffer or &false;, if
     output buffering isn't active.
    </para>
    <para>
     See also <function>ob_start</function> and
     <function>ob_get_length</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.ob-get-length">
   <refnamediv>
    <refname>ob_get_length</refname>
    <refpurpose>
     Return the length of the output buffer
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>ob_get_length</methodname>
      <void/>
     </methodsynopsis>
    <para>
     This will return the length of the contents in the output buffer
     or &false;, if output buffering isnt't active.
    </para>
    <para>
     See also <function>ob_start</function> and
     <function>ob_get_contents</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.ob-gzhandler">
   <refnamediv>
    <refname>ob_gzhandler</refname>
    <refpurpose>
     ob_start callback function to gzip output buffer
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>ob_gzhandler</methodname>
      <methodparam><type>string</type><parameter>buffer</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>ob_gzhandler</function> is intended to be used as a
     callback function for <function>ob_start</function> to help
     facilitate sending gz-encoded data to web browsers that support
     compressed web pages.  Before <function>ob_gzhandler</function>
     actually sends compressed data, it determines what type of
     content encoding the browser will accept ("gzip", "deflate" or
     none at all) and will return it's output accordingly.  All
     browsers are supported since it's up to the browser to send the
     correct header saying that it accepts compressed web pages.
    </para>
    <para>
     <example>
      <title><function>ob_gzhandler</function> Example</title>
      <programlisting role="php">
&lt;php

ob_start("ob_gzhandler");

?>
&lt;html&gt;
&lt;body&gt;
&lt;p&gt;This should be a compressed page.
&lt;/html&gt;
&lt;/body&gt;
      </programlisting>
     </example>
    </para>
    <para>
     See also <function>ob_start</function> and
     <function>ob_end_flush</function>.
    </para>
   </refsect1>
  </refentry>
 
  <refentry id="function.ob-end-flush">
   <refnamediv>
    <refname>ob_end_flush</refname> 
    <refpurpose>
     Flush (send) the output buffer and turn off output buffering    
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>void</type><methodname>ob_end_flush</methodname>
      <void/>
     </methodsynopsis>
    <para>
     This function will send the contents of the output buffer (if
     any) and turn output buffering off.  If you want to further
     process the buffer's contents you have to call
     <function>ob_get_contents</function> before
     <function>ob_end_flush</function> as the buffer contents are
     discarded after <function>ob_end_flush</function> is called.
    </para>
    <para>
     See also <function>ob_start</function>,
     <function>ob_get_contents</function>, and
     <function>ob_end_clean</function>.
    </para>
   </refsect1>
  </refentry>
 
  <refentry id="function.ob-end-clean">
   <refnamediv>
    <refname>ob_end_clean</refname> 
    <refpurpose>
     Clean (erase) the output buffer and turn off output buffering
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>void</type><methodname>ob_end_clean</methodname>
      <void/>
     </methodsynopsis>
    <para>
     This function discards the contents of the output buffer and
     turns off output buffering.
    </para>
    <para>
     See also <function>ob_start</function> and
     <function>ob_end_flush</function>.
    </para>
   </refsect1>
  </refentry>
 
  <refentry id="function.ob-implicit-flush">
   <refnamediv>
    <refname>ob_implicit_flush</refname> 
    <refpurpose>
     Turn implicit flush on/off 
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>void</type><methodname>ob_implicit_flush</methodname>
      <methodparam choice="opt"><type>int</type><parameter>flag</parameter></methodparam>		  
     </methodsynopsis>
    <para>
     <function>ob_implicit_flush</function> will turn implicit
     flushing on or off (if no <parameter>flag</parameter> is given,
     it defaults to on).  Implicit flushing will result in a flush
     operation after every output call, so that explicit calls to
     <function>flush</function> will no longer be needed.
    </para>
    <para>
     Turning implicit flushing on will disable output buffering, the
     output buffers current output will be sent as if
     <function>ob_end_flush</function> had been called.
    </para>
    <para>
     See also <function>flush</function>,
     <function>ob_start</function>, and
     <function>ob_end_flush</function>.
    </para>
   </refsect1>
  </refentry>

 </reference>

<!-- 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:"../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->