<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>Compression Filters</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="filters.convert.html">Conversion Filters</a></div>
<div class="next" style="text-align: right; float: right;"><a href="filters.encryption.html">Encryption Filters</a></div>
<div class="up"><a href="filters.html">List of Available Filters</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="filters.compression" class="section">
<h2 class="title">Compression Filters</h2>
<p class="simpara">
While the <a href="wrappers.compression.html" class="link">Compression Wrappers</a>
provide a way of creating
gzip and bz2 compatible files on the local filesystem, they do not provide a
means for generalized compression over network streams, nor do they provide a
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.
</p>
<blockquote class="note"><p><strong class="note">Note</strong>:
<span class="simpara">
Compression filters do <em class="emphasis">not</em> generate headers and trailers
used by command line utilities such as <em>gzip</em>. They only compress
and decompress the payload portions of compressed data streams.
</span>
</p></blockquote>
<p class="simpara">
<em>zlib.deflate</em> (compression) and
<em>zlib.inflate</em> (decompression) are implementations of
the compression methods described in <a href="http://www.faqs.org/rfcs/rfc1951" class="link external">» RFC 1951</a>.
The <em>deflate</em> filter takes up to three parameters passed as
an associative array.
<em><code class="parameter">level</code></em> 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).
<em><code class="parameter">window</code></em> 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 <em><code class="parameter">window</code></em> size is currently <strong><code>15</code></strong>.
<em><code class="parameter">memory</code></em> 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.
</p>
<blockquote class="note"><p><strong class="note">Note</strong>:
<span class="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).
</span>
</p></blockquote>
<p class="simpara">
zlib.* compression filters are available with PHP as of version <em>5.1.0</em> if
<a href="ref.zlib.html" class="link">zlib</a> support is enabled. They are also available as a backport in version
<em>5.0.x</em> by installing the <a href="http://pecl.php.net/package/zlib_filter" class="link external">» zlib_filter</a>
package from <a href="http://pecl.php.net/" class="link external">» PECL</a>. These filters are <em class="emphasis">not</em>
available for PHP 4.
</p>
<div class="example" id="example-5636">
<p><strong>Example #1
<em>zlib.deflate</em> and
<em>zlib.inflate</em>
</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br />$params </span><span style="color: #007700">= array(</span><span style="color: #DD0000">'level' </span><span style="color: #007700">=> </span><span style="color: #0000BB">6</span><span style="color: #007700">, </span><span style="color: #DD0000">'window' </span><span style="color: #007700">=> </span><span style="color: #0000BB">15</span><span style="color: #007700">, </span><span style="color: #DD0000">'memory' </span><span style="color: #007700">=> </span><span style="color: #0000BB">9</span><span style="color: #007700">);<br /><br /></span><span style="color: #0000BB">$original_text </span><span style="color: #007700">= </span><span style="color: #DD0000">"This is a test.\nThis is only a test.\nThis is not an important string.\n"</span><span style="color: #007700">;<br />echo </span><span style="color: #DD0000">"The original text is " </span><span style="color: #007700">. </span><span style="color: #0000BB">strlen</span><span style="color: #007700">(</span><span style="color: #0000BB">$original_text</span><span style="color: #007700">) . </span><span style="color: #DD0000">" characters long.\n"</span><span style="color: #007700">;<br /><br /></span><span style="color: #0000BB">$fp </span><span style="color: #007700">= </span><span style="color: #0000BB">fopen</span><span style="color: #007700">(</span><span style="color: #DD0000">'test.deflated'</span><span style="color: #007700">, </span><span style="color: #DD0000">'w'</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">stream_filter_append</span><span style="color: #007700">(</span><span style="color: #0000BB">$fp</span><span style="color: #007700">, </span><span style="color: #DD0000">'zlib.deflate'</span><span style="color: #007700">, </span><span style="color: #0000BB">STREAM_FILTER_WRITE</span><span style="color: #007700">, </span><span style="color: #0000BB">$params</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">fwrite</span><span style="color: #007700">(</span><span style="color: #0000BB">$fp</span><span style="color: #007700">, </span><span style="color: #0000BB">$original_text</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">fclose</span><span style="color: #007700">(</span><span style="color: #0000BB">$fp</span><span style="color: #007700">);<br /><br />echo </span><span style="color: #DD0000">"The compressed file is " </span><span style="color: #007700">. </span><span style="color: #0000BB">filesize</span><span style="color: #007700">(</span><span style="color: #DD0000">'test.deflated'</span><span style="color: #007700">) . </span><span style="color: #DD0000">" bytes long.\n"</span><span style="color: #007700">;<br />echo </span><span style="color: #DD0000">"The original text was:\n"</span><span style="color: #007700">;<br /></span><span style="color: #FF8000">/* Use readfile and zlib.inflate to decompress on the fly */<br /></span><span style="color: #0000BB">readfile</span><span style="color: #007700">(</span><span style="color: #DD0000">'php://filter/zlib.inflate/resource=test.deflated'</span><span style="color: #007700">);<br /><br /></span><span style="color: #FF8000">/* Generates output:<br /><br />The original text is 70 characters long.<br />The compressed file is 56 bytes long.<br />The original text was:<br />This is a test.<br />This is only a test.<br />This is not an important string.<br /><br /> */<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
<div class="example" id="example-5637">
<p><strong>Example #2
<em>zlib.deflate</em> simple
</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br />$original_text </span><span style="color: #007700">= </span><span style="color: #DD0000">"This is a test.\nThis is only a test.\nThis is not an important string.\n"</span><span style="color: #007700">;<br />echo </span><span style="color: #DD0000">"The original text is " </span><span style="color: #007700">. </span><span style="color: #0000BB">strlen</span><span style="color: #007700">(</span><span style="color: #0000BB">$original_text</span><span style="color: #007700">) . </span><span style="color: #DD0000">" characters long.\n"</span><span style="color: #007700">;<br /><br /></span><span style="color: #0000BB">$fp </span><span style="color: #007700">= </span><span style="color: #0000BB">fopen</span><span style="color: #007700">(</span><span style="color: #DD0000">'test.deflated'</span><span style="color: #007700">, </span><span style="color: #DD0000">'w'</span><span style="color: #007700">);<br /></span><span style="color: #FF8000">/* Here "6" indicates compression level 6 */<br /></span><span style="color: #0000BB">stream_filter_append</span><span style="color: #007700">(</span><span style="color: #0000BB">$fp</span><span style="color: #007700">, </span><span style="color: #DD0000">'zlib.deflate'</span><span style="color: #007700">, </span><span style="color: #0000BB">STREAM_FILTER_WRITE</span><span style="color: #007700">, </span><span style="color: #0000BB">6</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">fwrite</span><span style="color: #007700">(</span><span style="color: #0000BB">$fp</span><span style="color: #007700">, </span><span style="color: #0000BB">$original_text</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">fclose</span><span style="color: #007700">(</span><span style="color: #0000BB">$fp</span><span style="color: #007700">);<br /><br />echo </span><span style="color: #DD0000">"The compressed file is " </span><span style="color: #007700">. </span><span style="color: #0000BB">filesize</span><span style="color: #007700">(</span><span style="color: #DD0000">'test.deflated'</span><span style="color: #007700">) . </span><span style="color: #DD0000">" bytes long.\n"</span><span style="color: #007700">;<br /><br /></span><span style="color: #FF8000">/* Generates output:<br /><br />The original text is 70 characters long.<br />The compressed file is 56 bytes long.<br /><br /> */<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
<p class="simpara">
<em>bzip2.compress</em> and
<em>bzip2.decompress</em>
work in the same manner as the zlib filters described above.
The <em>bzip2.compress</em> filter accepts up to two parameters given as
elements of an associative array:
<em><code class="parameter">blocks</code></em> is an integer value
from 1 to 9 specifying the number of 100kbyte blocks of memory to allocate for
workspace.
<em><code class="parameter">work</code></em> 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 <em>bzip2.decompress</em> filter only accepts one parameter,
which can be passed as either an ordinary boolean value, or as the
<em><code class="parameter">small</code></em> element of an associative array.
<em><code class="parameter">small</code></em>, when set to a <strong><code>TRUE</code></strong> value, instructs the bzip library
to perform decompression in a minimal memory footprint at the cost of speed.
</p>
<p class="simpara">
bzip2.* compression filters are available with PHP as of version <em>5.1.0</em> if
<a href="ref.bzip2.html" class="link">bz2</a> support is enabled. They are also available as a backport in version
<em>5.0.x</em> by installing the <a href="http://pecl.php.net/package/bz2_filter" class="link external">» bz2_filter</a>
package from <a href="http://pecl.php.net/" class="link external">» PECL</a>. These filters are <em class="emphasis">not</em>
available for PHP 4.
</p>
<div class="example" id="example-5638">
<p><strong>Example #3
<em>bzip2.compress</em> and
<em>bzip2.decompress</em>
</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br />$param </span><span style="color: #007700">= array(</span><span style="color: #DD0000">'blocks' </span><span style="color: #007700">=> </span><span style="color: #0000BB">9</span><span style="color: #007700">, </span><span style="color: #DD0000">'work' </span><span style="color: #007700">=> </span><span style="color: #0000BB">0</span><span style="color: #007700">);<br /><br />echo </span><span style="color: #DD0000">"The original file is " </span><span style="color: #007700">. </span><span style="color: #0000BB">filesize</span><span style="color: #007700">(</span><span style="color: #DD0000">'LICENSE'</span><span style="color: #007700">) . </span><span style="color: #DD0000">" bytes long.\n"</span><span style="color: #007700">;<br /><br /></span><span style="color: #0000BB">$fp </span><span style="color: #007700">= </span><span style="color: #0000BB">fopen</span><span style="color: #007700">(</span><span style="color: #DD0000">'LICENSE.compressed'</span><span style="color: #007700">, </span><span style="color: #DD0000">'w'</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">stream_filter_append</span><span style="color: #007700">(</span><span style="color: #0000BB">$fp</span><span style="color: #007700">, </span><span style="color: #DD0000">'bzip2.compress'</span><span style="color: #007700">, </span><span style="color: #0000BB">STREAM_FILTER_WRITE</span><span style="color: #007700">, </span><span style="color: #0000BB">$param</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">fwrite</span><span style="color: #007700">(</span><span style="color: #0000BB">$fp</span><span style="color: #007700">, </span><span style="color: #0000BB">file_get_contents</span><span style="color: #007700">(</span><span style="color: #DD0000">'LICENSE'</span><span style="color: #007700">));<br /></span><span style="color: #0000BB">fclose</span><span style="color: #007700">(</span><span style="color: #0000BB">$fp</span><span style="color: #007700">);<br /><br />echo </span><span style="color: #DD0000">"The compressed file is " </span><span style="color: #007700">. </span><span style="color: #0000BB">filesize</span><span style="color: #007700">(</span><span style="color: #DD0000">'LICENSE.compressed'</span><span style="color: #007700">) . </span><span style="color: #DD0000">" bytes long.\n"</span><span style="color: #007700">;<br /><br /></span><span style="color: #FF8000">/* Generates output:<br /><br />The original text is 3288 characters long.<br />The compressed file is 1488 bytes long.<br /><br /> */<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
</div><hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="filters.convert.html">Conversion Filters</a></div>
<div class="next" style="text-align: right; float: right;"><a href="filters.encryption.html">Encryption Filters</a></div>
<div class="up"><a href="filters.html">List of Available Filters</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
