From 945c876b073eff09ac40452468732ea090a8b781 Mon Sep 17 00:00:00 2001
From: Sara Golemon <pollita@php.net>
Date: Fri, 16 Apr 2004 04:07:28 +0000
Subject: [PATCH] Document bzip2 filters

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@156218 c90b9560-bf6c-de11-be94-00142212c4b1
---
 appendices/filters.xml | 69 ++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 67 insertions(+), 2 deletions(-)

diff --git a/appendices/filters.xml b/appendices/filters.xml
index 66c363995b..756bb0195a 100644
--- a/appendices/filters.xml
+++ b/appendices/filters.xml
@@ -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 @@ fwrite($fp, "This is a test.\n");
    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 @@ The compressed file is 56 bytes long.
    </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>