pollita Fri Apr 16 00:07:28 2004 EDT
Modified files:
/phpdoc/en/appendices filters.xml
Log:
Document bzip2 filters
http://cvs.php.net/diff.php/phpdoc/en/appendices/filters.xml?r1=1.5&r2=1.6&ty=u
Index: phpdoc/en/appendices/filters.xml
diff -u phpdoc/en/appendices/filters.xml:1.5 phpdoc/en/appendices/filters.xml:1.6
--- phpdoc/en/appendices/filters.xml:1.5 Thu Apr 15 20:20:56 2004
+++ phpdoc/en/appendices/filters.xml Fri Apr 16 00:07:28 2004
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.5 $ -->
+<!-- $Revision: 1.6 $ -->
<appendix id="filters">
<title>List of Available Filters</title>
<para>
@@ -236,7 +236,7 @@
While the <xref linkend="wrappers.compression"/> provide a way of creating
gzip and bz2 compatable files on the local filesystem, they do not provide a
means for generalized compression over network streams, nor do they provide a
- means begin with a non-compressed stream and transition to a compressed one.
+ means to begin with a non-compressed stream and transition to a compressed one.
For this, a compression filter may be applied to any stream resource at any time.
</simpara>
@@ -353,6 +353,71 @@
</programlisting>
</example>
+ <simpara>
+ <literal>bzip2.compress</literal> and
+ <literal>bzip2.decompress</literal>
+ work in the same manner as the zlib filters described above.
+
+ The <literal>bzip2.compress</literal> filter accepts up to two parameters given as
+ elements of an associative array:
+
+ <parameter>blocks</parameter> is an integer value
+ from 1 to 9 specifying the number of 100kbyte blocks of memory to allocate for
+ workspace.
+
+ <parameter>work</parameter> is also an integer value ranging from
+ 0 to 250 indicating how much effort to expend using the normal compression method
+ before falling back on a slower, but more reliable method. Tuning this parameter
+ effects only compression speed. Neither size of compressed output nor memory usage
+ are changed by this setting. A work factor of 0 instructs the bzip library to use
+ an internal default.
+
+ The <literal>bzip2.decompress</literal> filter only accepts one parameter,
+ which can be passed as either an ordinary boolean value as the
+ <parameter>small</parameter> element of an associative array.
+
+ <parameter>small</parameter>, when set to a &true; value, instructs the bzip
library
+ to perform decompression in a minimal memory footprint at the cost of speed.
+ </simpara>
+
+ <note>
+ <simpara>
+ The bzip2.* filters are not currently built into the PHP core. To enable these
filters
+ in <literal>PHP 5</literal>, install the <ulink
url="&url.pecl.package;bz2_filter">bz2_filter</ulink>
+ package from <ulink url="&url.pecl;">PECL</ulink>. These filters are
<emphasis>not</emphasis>
+ available for <literal>PHP 4</literal>.
+ </simpara>
+ </note>
+
+ <example>
+ <title>
+ <literal>bzip2.compress</literal> and
+ <literal>bzip2.decompress</literal>
+ </title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$param = array('blocks' => 9, 'work' => 0);
+
+echo "The original file is " . filesize('LICENSE') . " bytes long.\n";
+
+$fp = fopen('LICENSE.compressed', 'w');
+stream_filter_append($fp, 'bzip2.compress', STREAM_FILTER_WRITE, $param);
+fwrite($fp, file_get_contents('LICENSE'));
+fclose($fp);
+
+echo "The compressed file is " . filesize('LICENSE.compressed') . " bytes long.\n";
+
+/* Generates output:
+
+The original text is 3288 characters long.
+The compressed file is 1488 bytes long.
+
+ */
+?>
+]]>
+ </programlisting>
+ </example>
</section>
</appendix>
