# Zlib Compression Functions

## Introduction

This module enables you to transparently read and write gzip (.gz) compressed files, through versions of most of the filesystem functions which work with gzip-compressed files (and uncompressed files, too, but not with sockets).

> Note: 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 prefix the filename or path with zlib: when calling fopen(). This feature requires a C runtime library that provides the fopencookie() function. Up to now the GNU libc seems to be the only library that provides this feature.
> In PHP 4.3.0, zlib: has been changed to compress.zlib:// to prevent ambiguities with filenames containing ':' characters. The fopencookie() function is not longer required. More information is available in the section about Compression Streams.

## Requirements

This module uses the functions of » zlib by Jean-loup Gailly and Mark Adler. You have to use a zlib version >= 1.0.9 with this module.

## Installation

Zlib support in PHP is not enabled by default. You will need to configure PHP --with-zlib[=DIR]

The windows version of PHP has built in support for this extension. You do not need to load any additional extension in order to use these functions.

> Note: Built-in support for zlib on Windows is available with PHP 4.3.0.

## Runtime Configuration

The behaviour of these functions is affected by settings in php.ini.

The zlib extension offers the option to transparently compress your pages on-the-fly, if the requesting browser supports this. Therefore there are three options in the configuration file php.ini.

Zlib Configuration Options
Name | Default | Changeable | Changelog
--- | --- | --- | ---
zlib.output_compression | "0" | PHP_INI_ALL | Available since PHP 4.0.5.
zlib.output_compression_level | "-1" | PHP_INI_ALL | Available since PHP 4.3.0.
zlib.output_handler | "" | PHP_INI_ALL | Available since PHP 4.3.0.

For further details and definitions of the PHP_INI_* constants, see the php.ini directives.

Here's a short explanation of the configuration directives.

`zlib.output_compression` boolean/integer

  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. In runtime, it can be set only before sending any output.

  This option also accepts integer values instead of boolean "On"/"Off", using this you can set the output buffer size (default is 4KB).

  > Note: output_handler must be empty if this is set 'On' ! Instead you must use zlib.output_handler.

`zlib.output_compression_level` integer

  Compression level used for transparent output compression.

`zlib.output_handler` string

  You cannot specify additional output handlers if zlib.output_compression is activated here. This setting does the same as output_handler but in a different order.

## Resource Types

This extension defines a file pointer resource returned by gzopen().

## Predefined Constants

The constants below are defined by this extension, and will only be available when the extension has either been compiled into PHP or dynamically loaded at runtime.

`FORCE_GZIP` (integer)
`FORCE_DEFLATE` (integer)

## Examples

This example opens a temporary file and writes a test string to it, then it prints out the content of this file twice.

Example#1 Small Zlib Example

`<?php
$filename = tempnam('/tmp', 'zlibtest') . '.gz';
echo "<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
echo gzread($zp, 3);
// output until end of the file and close it.
gzpassthru($zp);
gzclose($zp);
echo "\n";
// open file and print content (the 2nd time).
if (readgzfile($filename) != strlen($s)) {
echo "Error with zlib functions!";
}
unlink($filename);
echo "</pre>\n</body>\n</html>\n";
?>`

## Table of Contents

- gzclose — Close an open gz-file pointer
- gzcompress — Compress a string
- gzdecode — Decodes a gzip compressed string
- gzdeflate — Deflate a string
- gzencode — Create a gzip compressed string
- gzeof — Test for end-of-file on a gz-file pointer
- gzfile — Read entire gz-file into an array
- gzgetc — Get character from gz-file pointer
- gzgets — Get line from file pointer
- gzgetss — Get line from gz-file pointer and strip HTML tags
- gzinflate — Inflate a deflated string
- gzopen — Open gz-file
- gzpassthru — Output all remaining data on a gz-file pointer
- gzputs — Alias of gzwrite
- gzread — Binary-safe gz-file read
- gzrewind — Rewind the position of a gz-file pointer
- gzseek — Seek on a gz-file pointer
- gztell — Tell gz-file pointer read/write position
- gzuncompress — Uncompress a compressed string
- gzwrite — Binary-safe gz-file write
- readgzfile — Output a gz-file
- zlib_get_coding_type — Returns the coding type used for output compression