danbeck Tue Feb 6 15:00:58 2001 EDT
Modified files:
/phpdoc/en/functions outcontrol.xml
Log:
added docs for ob_gzhandler and references in ob_start()
Index: phpdoc/en/functions/outcontrol.xml
diff -u phpdoc/en/functions/outcontrol.xml:1.10 phpdoc/en/functions/outcontrol.xml:1.11
--- phpdoc/en/functions/outcontrol.xml:1.10 Sun Dec 10 17:44:01 2000
+++ phpdoc/en/functions/outcontrol.xml Tue Feb 6 15:00:58 2001
@@ -102,9 +102,9 @@
</funcprototype>
</funcsynopsis>
<para>
- This function will turn output buffering on. While output buffering
- is active no output is sent from the script, instead the output
- is stored in an internal buffer.
+ 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
@@ -115,52 +115,81 @@
buffer contents.
</para>
<para>
- An optional output_callback function may be specified. This
- function takes a string as a parameter and returns a string.
- The function will be called at <function>ob_end_flush</function>
- time and will receive the contents of the output buffer as its
- parameter. It must return a new output buffer as a result,
- which is what will be printed.
- </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>
+ 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>Callback function example</title>
+ <title>User defined callback function example</title>
<programlisting role="php">
<?php
-function c($str) {
- // Druu Chunusun mut dum Kuntrubuß...
- return nl2br(ereg_replace("[aeiou]", "u", $str));
-}
+
+function callback($buffer) {
-function d($str) {
- return strip_tags($str);
+ // 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_start("c"); ?>
-Drei Chinesen mit dem Kontrabaß...
-<?php ob_start("d"); ?>
-<h1>..saßen auf der Straße und erzählten sich was...</h1>
-<?php ob_end_flush(); ?>
-... da kam die Polizei, ja was ist denn das?
-<?php ob_end_flush(); ?>
+<?php
+
+ob_end_flush();
?>
</programlisting>
</example>
<para>
+ Would produce:
+ <informalexample>
+ <programlisting role="php">
+<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>, and
- <function>ob_implicit_flush</function>
+ <function>ob_end_clean</function>,
+ <function>ob_implicit_flush</function> and
+ <function>ob_gzhandler</function>.
</para>
</refsect1>
</refentry>
@@ -213,6 +242,56 @@
<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">
+<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>
