# Compressed File Functions PHP

The functions in this section use the zlib library to work with files compressed with GNU compression tools, such as gzip. The library was written by Jean-loup Gaill and Mark Adler. The two are authors of the gzip tool, in fact.

In order to activate these functions, you must include the zlib extension. On a UNIX operating system, you configure PHP to use zlib as you compile it. On Windows you may activate the php_zlib.dll extension either in php.ini or using the dl function.

Most of the functions for reading and writing files are duplicated here and they operate similarly. One difference is the lack of support for specifying files using HTTP or FTP protocol.

boolean gzclose(integer file_handle)
The gzclose function closes a file opened with gzopen. TRUE is returned if the file closed successfully. FALSE is returned if the file cannot be closed. See gzgets for an example of use.

boolean gzeof(integer file_handle)
As you read from a compressed file, PHP keeps a pointer to the last place in the file you read. The gzeof function returns TRUE if you are at the end of the file. See gzgets for an example of use.

array gzfile(string filename, boolean use_include_path)
The gzfile function reads an entire file into an array. The file is first uncompressed. Each line of the file is a separate element of the array, starting at zero. The optional use_include_path argument causes gzfile to search for the file within the include path specified in php.ini.

// open file and print each line
$myFile = gzfile( "data.gz"); for($index = 0; $index < count($myFile); $index++) { print($myFile[$index]); } ?> string gzgetc(integer file_handle) The gzgetc function returns a single character from a compressed file. It expects a file handle as returned by gzopen. <? // open compressed file and print each character if($myFile = gzopen("data.gz", "r"))
{
while(!gzeof($myFile)) {$myCharacter = gzgetc($myFile); print($myCharacter);
}
gzclose($myFile); } ?> string gzgets(integer file_handle, integer length) The gzgets function returns a string it reads from a compressed file specified by the file handle, which must have been created with gzopen. It will attempt to read as many characters as specified by the length argument less one (presumably this is PHP showing its C heritage). A linebreak is treated as a stopping point, as is the end of the file. Linebreaks are included in the return string. <? // open file and print each line if($myFile = gzopen("data.gz", "r"))
{
while(!gzeof($myFile)) {$myLine = gzgets($myFile, 255); print($myLine);
}
gzclose($myFile); } ?> string gzgetss(integer file_handle, integer length, string ignore) The gzgetss function is in all respects identical to gzgets except that it attempts to strip any HTML or PHP code before returning a string. The optional ignore argument may contain tags to be ignored. <? // open compressed file and print each line if($myFile = gzopen("data.gz", "r"))
{
while(!gzeof($myFile)) {$myLine = gzgetss($myFile, 255); print($myLine);
}
gzclose($myFile); } ?> integer gzopen(string filename, string mode, boolean use_include_path) The gzopen function is similar in operation to the fopen function, except that it operates on compressed files. If the use_include_path argument is TRUE, the include path specified in php.ini will be searched. See gzgets and gzputs for examples of use. The mode argument accepts a few extra parameters compared to fopen. In addition to the modes listed, you may specify a compression level and a compression strategy if you are creating a new file. Immediately following the write mode, you may place an integer between zero and nine that specifies the level of compression. Zero means no compression, and nine is maximum compression. After the compression level,you may use h to force Huffman encoding only, or f to optimize for filtered input. Filtered data is defined by the zlib source code as being small values of somewhat random distribution. In almost all cases the default settings are a good choice and the extra mode settings are unnecessary.It is possible to open an uncompressed file with gzopen. Reads from the file will operate as expected. This can be convenient if you do not know ahead of time whether a file is compressed. boolean gzpassthru(integer file_handle) The gzpassthru function prints the contents of the compressed file to the browser, exactly like the fpassthru function. <? // open a compressed file if(!($myFile = gzopen("data.html.gz", "r")))
{
print("file could not be opened");
exit;
}
// send the entire file to browser
gzpassthru($myFile); ?> boolean gzputs(int file_handle, string output, integer length) The gzputs function writes data to a compressed file. It expects a file handle as returned by gzopen. It returns TRUE if the write was successful, FALSE if it failed. The optional length argument specifies a maximum number of input bytes to accept. A side effect of specifying length is that the magic_ quotes_runtime configuration setting will be ignored. <? // open file for writing // use maximum compress and force // Huffman encoding only$myFile = gzopen("data.gz","wb9h");
// make sure the open was successful
if(!($myFile)) { print("file could not be opened"); exit; } for($index=0; $index<10;$index++)
{
// write a line to the file
gzputs($myFile, "line$indexn");
}
// close the file
gzclose($myFile); ?> gzread The gzread function is an alias to gzgets. boolean gzrewind(integer file_handle) The gzrewind function moves PHP's internal file pointer back to the beginning of a compressed file. It returns TRUE on success, FALSE if there is an error. <? /* ** print a file, then print the first line again */ // open a local file if(!($myFile = gzopen("data.gz", "r")))
{
print("file could not be opened");
exit;
}
while(!gzeof($myFile)) { // read a line from the file$myLine = gzgetss($myFile, 255); print("$myLine <BR>n");
}
gzrewind($myFile);$myLine = gzgetss($myFile, 255); print("$myLine <BR>n");
// close the file
gzclose($myFile); ?> integer gzseek(integer file_handle, integer offset) This function works exactly like fseek, except that it operates on compressed files. <? // open a file if(!($myFile = gzopen("data.gz", "r")))
{
print("file could not be opened");
exit;
}
// jump 32 bytes into the file
gzseek($myFile, 32);$myLine = gzgets($myFile, 255); print($myLine);
// dump the rest of the file
gzpassthru($myFile); ?> integer gztell(integer file_handle) Given a valid file handle, gztell returns the offset of PHP's internal file pointer. <? // open a file if(!($myFile = gzopen("data.gz", "r")))
{
print("file could not be opened");
exit;
}
$myLine = gzgets($myFile, 255);
print($myLine); print("<HR>n"); print("File pointer at " . gztell($myFile) . " bytes");
// close file
gzclose(\$myFile);
?>

gzwrite
The gzwrite function is an alias to gzputs.