cvs: phpdoc /en/appendices filters.xml

pollita Thu Apr 15 20:20:56 2004 EDT Modified files: /phpdoc/en/appendices filters.xml Log: Document zlib filters http://cvs.php.net/diff.php/phpdoc/en/appendices/filters.xml?r1=1.4&r2=1.5&ty=u Index: phpdoc/en/appendices/filters.xml diff -u phpdoc/en/appendices/filters.xml:1.4 phpdoc/en/appendices/filters.xml:1.5 --- phpdoc/en/appendices/filters.xml:1.4 Thu Apr 15 11:38:49 2004 +++ phpdoc/en/appendices/filters.xml Thu Apr 15 20:20:56 2004 @@ -1,7 +1,7 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.4 $ --> +<!-- $Revision: 1.5 $ --> <appendix id="filters"> - <title>List of Built-In Filters</title> + <title>List of Available Filters</title> <para> The following is a list of a few built-in stream filters for use with <function>stream_filter_append</function>. @@ -229,6 +229,132 @@ </example> </section> + <section id="filters.compression"> + <title>Compression Filters</title> + + <simpara> + 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. + For this, a compression filter may be applied to any stream resource at any time. + </simpara> + + <note> + <simpara> + Compression filters do <emphasis>not</emphasis> generate headers and trailers + used by commandline utilites such as <literal>gzip</literal>. They only compress + and decompress the payload portions of compressed data streams. + </simpara> + </note> + + <simpara> + <literal>zlib.deflate</literal> (compression) and + <literal>zlib.inflate</literal> (decompression) are implementations of + the compression methods described in <ulink url="&url.rfc;1951">RFC 1951</ulink>. + The <literal>deflate</literal> filter takes up to three parameters passed as + an associative array. + + <parameter>level</parameter> describes the compression + strength to use (1-9). Higher numbers will generally yield smaller payloads at + the cost of additional processing time. Two special compression levels also exist: + 0 (for no compression at all), and -1 (zlib internal default -- currently 6). + + <parameter>window</parameter> is the base-2 log of the compression loopback window size. + Higher values (up to 15 -- 32768 bytes) yield better compression at a cost of memory, + while lower values (down to 9 -- 512 bytes) yield worse compression in a smaller memory footprint. + Default <parameter>window</parameter> size is currently <constant>15</constant>. + + <parameter>memory</parameter> is a scale indicating how much work memory should be allocated. + Valid values range from 1 (minimal allocation) to 9 (maximum allocation). This memory allocation + affects speed only and does not impact the size of the generated payload. + </simpara> + + <note> + <simpara> + Because compression level is the most commonly used parameter, it may be alternatively + provided as a simple integer value (rather than an array element). + </simpara> + </note> + + <note> + <simpara> + The zlib.* 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;zlib_filter">zlib_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>zlib.deflate</literal> and + <literal>zlib.inflate</literal> + </title> + <programlisting role="php"> +<![CDATA[ +<?php +$params = array('level' => 6, 'window' => 15, 'memory' => 9); + +$original_text = "This is a test.\nThis is only a test.\nThis is not an important string.\n"; +echo "The original text is " . strlen($original_text) . " characters long.\n"; + +$fp = fopen('test.deflated', 'w'); +stream_filter_append($fp, 'zlib.deflate', STREAM_FILTER_WRITE, $params); +fwrite($fp, $original_text); +fclose($fp); + +echo "The compressed file is " . filesize('test.deflated') . " bytes long.\n"; +echo "The original text was:\n"; +/* Use readfile and zlib.inflate to decompress on the fly */ +readfile('php://filter/zlib.inflate/resource=test.deflated'); + +/* Generates output: + +The original text is 70 characters long. +The compressed file is 56 bytes long. +The original text was: +This is a test. +This is only a test. +This is not an important string. + + */ +?> +]]> + </programlisting> + </example> + + <example> + <title> + <literal>zlib.deflate</literal> simple + </title> + <programlisting role="php"> +<![CDATA[ +<?php +$original_text = "This is a test.\nThis is only a test.\nThis is not an important string.\n"; +echo "The original text is " . strlen($original_text) . " characters long.\n"; + +$fp = fopen('test.deflated', 'w'); +/* Here "6" indicates compression level 6 */ +stream_filter_append($fp, 'zlib.deflate', STREAM_FILTER_WRITE, 6); +fwrite($fp, $original_text); +fclose($fp); + +echo "The compressed file is " . filesize('test.deflated') . " bytes long.\n"; + +/* Generates output: + +The original text is 70 characters long. +The compressed file is 56 bytes long. + + */ +?> +]]> + </programlisting> + </example> + + </section> + </appendix> <!-- Keep this comment at the end of the file