mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-20 19:08:54 +00:00
3747b34a1b
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@64852 c90b9560-bf6c-de11-be94-00142212c4b1
523 lines
15 KiB
XML
523 lines
15 KiB
XML
<?xml version="1.0" encoding="iso-8859-1"?>
|
|
<!-- $Revision: 1.23 $ -->
|
|
<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">
|
|
<![CDATA[
|
|
<?php
|
|
|
|
ob_start();
|
|
echo "Hello\n";
|
|
|
|
setcookie ("cookiename", "cookiedata");
|
|
|
|
ob_end_flush();
|
|
|
|
?>
|
|
]]>
|
|
</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>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void <function>flush</function></funcdef>
|
|
<void/>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<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 </table> tag of the outermost table is
|
|
seen.
|
|
</para>
|
|
<para>
|
|
Some versions of Microsoft Internet Explorer will only start to display
|
|
the page after they have received 256 bytes of output, so you may need to
|
|
send extra whitespace before flushing to get those browsers to display the
|
|
page.
|
|
</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>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void <function>ob_start</function></funcdef>
|
|
<paramdef>string
|
|
<parameter>
|
|
<optional>output_callback</optional>
|
|
</parameter>
|
|
</paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<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">
|
|
<![CDATA[
|
|
<?php
|
|
|
|
function callback($buffer) {
|
|
|
|
// replace all the apples with oranges
|
|
return (ereg_replace("apples", "oranges", $buffer));
|
|
|
|
}
|
|
|
|
ob_start("callback");
|
|
|
|
?>
|
|
|
|
<html>
|
|
<body>
|
|
<p>It's like comparing apples to oranges.
|
|
</body>
|
|
</html>
|
|
|
|
<?php
|
|
|
|
ob_end_flush();
|
|
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
<para>
|
|
Would produce:
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<html>
|
|
<body>
|
|
<p>It's like comparing oranges to oranges.
|
|
</body>
|
|
</html>
|
|
]]>
|
|
</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>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>string <function>ob_get_contents</function></funcdef>
|
|
<void/>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<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>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>string <function>ob_get_length</function></funcdef>
|
|
<void/>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<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-get-level">
|
|
<refnamediv>
|
|
<refname>ob_get_level</refname>
|
|
<refpurpose>
|
|
Return the nesting level of the output buffering mechanism
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>ob_get_level</function></funcdef>
|
|
<void/>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
This will return the level of nested output buffering handlers.
|
|
</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>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>string <function>ob_gzhandler</function></funcdef>
|
|
<paramdef>string <parameter>buffer</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<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">
|
|
<![CDATA[
|
|
<?php
|
|
|
|
ob_start("ob_gzhandler");
|
|
|
|
?>
|
|
<html>
|
|
<body>
|
|
<p>This should be a compressed page.
|
|
</html>
|
|
<body>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
See also <function>ob_start</function> and
|
|
<function>ob_end_flush</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.ob-flush">
|
|
<refnamediv>
|
|
<refname>ob_flush</refname>
|
|
<refpurpose>
|
|
Flush (send) the output buffer
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void <function>ob_flush</function></funcdef>
|
|
<void/>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
This function will send the contents of the output buffer (if
|
|
any). If you want to further
|
|
process the buffer's contents you have to call
|
|
<function>ob_get_contents</function> before
|
|
<function>ob_flush</function> as the buffer contents are
|
|
discarded after <function>ob_flush</function> is called.
|
|
</para>
|
|
<para>
|
|
This function does not destroy the output buffer like
|
|
<function>ob_end_flush</function> does.
|
|
</para>
|
|
<para>
|
|
See also <function>ob_get_contents</function>,
|
|
<function>ob_clean</function>,
|
|
<function>ob_end_flush</function> and
|
|
<function>ob_end_clean</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.ob-clean">
|
|
<refnamediv>
|
|
<refname>ob_clean</refname>
|
|
<refpurpose>
|
|
Clean (erase) the output buffer
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void <function>ob_clean</function></funcdef>
|
|
<void/>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
This function discards the contents of the output buffer.
|
|
</para>
|
|
<para>
|
|
This function does not destroy the output buffer like
|
|
<function>ob_end_clean</function> does.
|
|
</para>
|
|
<para>
|
|
See also <function>ob_flush</function>,
|
|
<function>ob_end_flush</function> and
|
|
<function>ob_end_clean</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>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void <function>ob_end_flush</function></funcdef>
|
|
<void/>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<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>,
|
|
<function>ob_flush</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>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void <function>ob_end_clean</function></funcdef>
|
|
<void/>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
This function discards the contents of the output buffer and
|
|
turns off output buffering.
|
|
</para>
|
|
<para>
|
|
See also <function>ob_start</function>,
|
|
<function>ob_clean</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>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void <function>ob_implicit_flush</function></funcdef>
|
|
<paramdef>int
|
|
<parameter><optional>flag</optional></parameter>
|
|
</paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<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:
|
|
vim600: syn=xml fen fdm=syntax fdl=2 si
|
|
vim: et tw=78 syn=sgml
|
|
vi: ts=1 sw=1
|
|
-->
|