The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
CGI-Compress-Gzip-0.04
River stage one • 1 direct dependent • 1 total dependent
/ CGI::Compress::Gzip

NAME

CGI::Compress::Gzip - CGI with automatically compressed output

SYNOPSIS

use CGI::Compress::Gzip;

my $cgi = new CGI::Compress::Gzip;
print $cgi->header();
print "<html> ...";

DESCRIPTION

[This is still alpha code, but it works in some environments. See README for caveats.]

CGI::Compress::Gzip extends the CGI class to auto-detect whether the client browser wants compressed output and, if so and if the script chooses HTML output, apply gzip compression on any content header for STDOUT. This module is intended to be a drop-in replacement for CGI.pm in a typical scripting environment.

Apache mod_perl users may wish to consider the Apache::Compress or Apache::GzipChain modules, which allow more transparent output compression than this module can provide. However, as of this writing those modules are more aggressive about compressing, regardless of Content-Type.

Headers

At the time that a header is requested, CGI::Compress::Gzip checks the HTTP_ACCEPT_ENCODING environment variable (passed by Apache). If this variable includes the flag "gzip" and the outgoing mime-type is "text/*", then gzipped output is prefered. The header is altered to add the "Content-Encoding: gzip" flag which indicates that compression is turned on.

Naturally, it is crucial that the CGI application output nothing before the header is printed. If this is violated, things will go badly.

Compression

When the header is created, this module sets up a new filehandle to accept data. STDOUT is redirected through that filehandle. The new filehandle passes data verbatim until it detects the end of the CGI header. At that time, it switches over to Gzip output for the remainder of the CGI run.

CLASS METHODS

new <CGI-ARGS>

Create a new object. This resets the environment before creating a CGI.pm object. This should not be called more than once per script run! All arguments are passed to the parent class.

useCompression 1|0

Turn compression on/off for all CGI::Compress::Gzip objects. If turned on, compression will be used only if the prerequisite compression libraries are available and if the client browser requests compression.

INSTANCE METHODS

useFileHandle FILEHANDLE

Manually set the output filehandle. Because of limitations of libz, this MUST be a real filehandle (with valid results from fileno()) and not a pseudo filehandle like IO::String.

If this is not set, STDOUT is used.

header HEADER-ARGS

Return a CGI header with the compression flags set properly. Returns an empty string is a header has already been printed.

This method engages the Gzip output by fiddling with the default output filehandle. All subsequent output via usual Perl print() will be automatically gzipped except for this header (which must go out as plain text).

Any arguments will be passed on to CGI::header. This method should NOT be called if you don't want your header or STDOUT to be fiddled with.

DESTROY

Override the CGI destructor so we can close the Gzip output stream, if there is one open.

HELPER CLASS

CGI::Compress::Gzip also implements a helper class in package my::Zlibwrapper which subclasses IO::Zlib. This helper is needed to make sure that output is not compressed until the CGI header is emitted. This wrappers delays the ignition of the zlib filter until it sees the exact same header generated by CGI::Compress::Gzip::header() pass through it's WRITE() method. If you change the header before printing it, this class will throw an exception.

This class hold one global variable representing the previous default filehandle used before the gzip filter is put in place. This filehandle, usually STDOUT, is replaced after the gzip stream finishes (which is usually when the CGI object goes out of scope and is destroyed).

TO DO

* Fix in mod_perl, test in FastCGI environments

* Handle errors more gracefully in WRITE()

* Use memGzip instead of IO::Zlib when output is not a real file handle

SEE ALSO

CGI::Compress::Gzip depends on CGI and IO::Zlib. Related functionality is available from Apache::Compress or Apache::GzipChain.

AUTHOR

Chris Dolan, Clotho Advanced Media, chris@clotho.com

LICENSE

GPLv2, see the COPYING file in this distribution.