cvs: phpdoc /en/appendices filters.xml

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>