php-doc-en/reference/zlib/reference.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.7 $ -->
 <reference id="ref.zlib">
  <title>Zlib Compression Functions</title>
  <titleabbrev>Zlib</titleabbrev>

  <partintro>
   <section id="zlib.intro">
    &reftitle.intro;
    <para>
     This module enables you to transparently read and write
     gzip (.gz) compressed files, through versions of most of
     the <link linkend="ref.filesystem">filesystem</link> functions
     which work with gzip-compressed files (and uncompressed files,
     too, but not with sockets).
    </para>
    <note>
     <para>
      Version 4.0.4 introduced a fopen-wrapper for .gz-files, so that
      you can use a special 'zlib:' URL to access compressed files
      transparently using the normal f*() file access functions if you
      prepend the filename or path with a 'zlib:' prefix when calling
      <function>fopen</function>.
     </para>
     <para>
      In version 4.3.0, this special prefix has been changed to 'zlib://'
      to prevent ambiguities with filenames containing ':'.
     </para>
     <para>
      This feature requires a C runtime library that provides the
      <literal>fopencookie()</literal> function. To my current
      knowledge the GNU libc is the only library that provides
      this feature.
     </para>
    </note>
   </section>

   <section id="zlib.requirements">
    &reftitle.required;
    <para>
     This module uses the functions of <ulink url="&url.zlib;">zlib</ulink>
     by Jean-loup Gailly and Mark Adler. You have to use a zlib
     version &gt;= 1.0.9 with this module.
    </para>
   </section>

   <section id="zlib.configuration">
    &reftitle.runtime;
    <para>
     The zlib extension offers the option to transparently compress
     your pages on-the-fly, if the requesting browser supports
     this. Therefore there are two options in the <link
     linkend="configuration.file">configuration file</link> &php.ini;.

     <table>
      <title>Zlib Configuration Options</title>
      <tgroup cols="3">
       <thead>
        <row>
         <entry>Name</entry>
         <entry>Default</entry>
         <entry>Changeable</entry>
        </row>
       </thead>
       <tbody>
        <row>
         <entry>zlib.output_compression</entry>
         <entry>"0"</entry>
         <entry>PHP_INI_ALL</entry>
        </row>
        <row>
         <entry>zlib.output_compression_level</entry>
         <entry>"-1"</entry>
         <entry>PHP_INI_ALL</entry>
        </row>
       </tbody>
      </tgroup>
     </table>

     For further details and definition of the PHP_INI_* constants see
     <function>ini_set</function>.
   </para>

   <para>
    Here is a short explanation of the configuration directives.
    <variablelist>
     <varlistentry id="ini.zlib.output_compression">
      <term>
       <parameter>zlib.output_compression</parameter>
       <type>boolean</type>/<type>integer</type>
      </term>
      <listitem>
       <para>
        Whether to transparently compress pages. If this option is set
        to "On" in &php.ini; or the Apache configuration, pages are
        compressed if the browser sends an "Accept-Encoding: gzip" or
        "deflate" header. "Content-Encoding: gzip" (respectively
        "deflate") and "Vary: Accept-Encoding" headers are added to
        the output.
       </para>
       <para>
        You can use <function>ini_set</function> to disable this in
        your script if the headers aren't already sent. If you output
        a "Content-Type: image/" header the compression is disabled,
        too (in order to circumvent a Netscape bug). You can reenable
        it, if you add "ini_set('zlib.output_compression', 'On')"
        after the header call which added the image content-type.
       </para>
       <para>
        This option also accepts integer values instead of boolean
        "On"/"Off", using this you can set the output buffer size.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry id="ini.zlib.output_compression_level">
      <term>
       <parameter>zlib.output_compression_level</parameter>
       <type>integer</type>
      </term>
      <listitem>
       <para>
        Compression level used for transparent output compression.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
    </para>
   </section>

   <section id="zlib.resources">
    &reftitle.resources;
    &no.resource;
   </section>

   &reference.zlib.constants;

   <section id="zlib.examples">
    &reftitle.examples;
    <para>
     This example opens a temporary file and writes a test string 
     to it, then it prints out the content of this file twice.
    </para>
    <example>
     <title>Small Zlib Example</title>
     <programlisting role="php">
<![CDATA[
<?php

$filename = tempnam ('/tmp', 'zlibtest').'.gz';
print "<html>\n<head></head>\n<body>\n<pre>\n";
$s = "Only a test, test, test, test, test, test, test, test!\n";

// open file for writing with maximum compression
$zp = gzopen($filename, "w9");

// write string to file
gzwrite($zp, $s);

// close file
gzclose($zp);

// open file for reading
$zp = gzopen($filename, "r");

// read 3 char
print gzread($zp, 3);

// output until end of the file and close it.
gzpassthru($zp);

print "\n";

// open file and print content (the 2nd time).
if (readgzfile($filename) != strlen($s)) {
        echo "Error with zlib functions!";
}
unlink($filename);
print "</pre>\n</h1></body>\n</html>\n";

?>
]]>
     </programlisting>
    </example>
   </section>
  </partintro>

&reference.zlib.functions;

 </reference>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->