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

LICENSE
    Copyright 2006-2007 Clotho Advanced Media, Inc., <cpan@clotho.com>

    Copyright 2007-2008 Chris Dolan <cdolan@cpan.org>

    This library is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.

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

    See the CAVEATS section below!

DESCRIPTION
    CGI::Compress::Gzip extends the CGI module 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.

    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 preferred. [the default mime-type
    selection of text/* can be changed by subclassing -- see below] 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.

    Note that the Zlib library on which this code is ultimately based
    requires a fileno for the output filehandle. Where the output filehandle
    is faked (i.e. in mod_perl), we instead use in-memory compression. This
    is more wasteful of RAM, but it is the only solution I've found (and it
    is one shared by the Apache::* compression modules).

    Debugging note: if you set $CGI::Compress::Gzip::global_give_reason to a
    true value, then this module will add an HTTP header entry called
    X-non-gzip-reason with an explanation of why it chose not to gzip the
    output stream.

  Buffering

    The Zlib library introduces latencies. In some cases, this module may
    delay output until the CGI object is garbage collected, presumably at
    the end of the program. This buffering can be detrimental to long-lived
    programs which are supposed to have incremental output, causing browser
    timeouts. To compensate, compression is automatically disabled when
    autoflush (i.e. the $| variable) is set to true. Future versions may try
    to enable autoflushing on the Zlib filehandles, if possible [Help
    wanted].

CLASS METHODS
    $pkg->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.

    $pkg->useCompression($boolean)
    $self->useCompression($boolean)
        This can be used as a class method or an instance method. The former
        is included for backward compatibility, and is NOT recommended. As a
        class method, this changes the default value. As an instance method
        it affects only the specified instance.

        Turn compression on/off for the target. If turned on, compression
        will be used only if the prerequisite compression libraries are
        available and if the client browser requests compression.

        Defaults to on.

INSTANCE METHODS
    $self->useFileHandle($filehandle)
        Manually set the output filehandle. Because of limitations of Zlib,
        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.

    $self->isCompressibleType($content_type)
        Given a MIME type (with possible charset attached), return a boolean
        indicating if this media type is a good candidate for compression.
        This implementation is simply:

            return $type =~ /^text\//;

        Subclasses may wish to override this method to apply different
        criteria.

    $self->header([HEADER ARGS])
        Overrides the `header()' method in CGI.

        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.

    $self->DESTROY()
        Override the CGI destructor so we can close the Gzip output stream,
        if there is one open.

CAVEATS
  Apache::Registry

    Under Apache::Registry, global variables may not go out of scope in
    time. This may causes timing bugs, since this module makes use of the
    DESTROY() method. To avoid this issue, make sure your CGI object is
    stored in a scoped variable.

       # BROKEN CODE
       use CGI::Compress::Gzip;
       $q = CGI::Compress::Gzip->new;
       print $q->header;
       print "Hello, world\n";
   
       # WORKAROUND CODE
       use CGI::Compress::Gzip;
       do {
         my $q = CGI::Compress::Gzip->new;
         print $q->header;
         print "Hello, world\n";
       }

  Filehandles

    This module works by changing the default filehandle. It does not change
    STDOUT at all. As a consequence, your programs should call `print'
    without a filehandle argument.

       # BROKEN CODE
       use CGI::Compress::Gzip;
       my $q = CGI::Compress::Gzip->new;
       print STDOUT $q->header;
       print STDOUT "Hello, world\n";
   
       # WORKAROUND CODE
       use CGI::Compress::Gzip;
       my $q = CGI::Compress::Gzip->new;
       print $q->header;
       print "Hello, world\n";

    Future versions may steal away STDOUT and replace it with the
    compression filehandle, but that seemed too risky for this version.

  Header Munging

    When sending compressed output, the HTTP headers must remain
    uncompressed. So, this module goes to great effort to keep the headers
    and body separate. That has led to CGI::header() emulation code that is
    a little brittle. Most potential problems arise because STDOUT gets
    tweaked as soon as header() is called.

    If you use the CGI.pm header() API as specified in CGI.pm, then all
    should go well. But if you do anything unusual, this module may break.
    For example:

       # BROKEN CODE
       use CGI::Compress::Gzip;
       my $q = CGI::Compress::Gzip->new;
       print "Set-Cookie: foo=bar\n" . $q->header;
       print "Hello, world\n";

       # WORKAROUND 1 (preferred)
       use CGI::Compress::Gzip;
       my $q = CGI::Compress::Gzip->new;
       print $q->header("-Set_Cookie" => "foo=bar");
       print "Hello, world\n";

       # WORKAROUND 2
       use CGI::Compress::Gzip;
       my $q = CGI::Compress::Gzip->new;
       print "Set-Cookie: foo=bar\n";
       print $q->header;
       print "Hello, world\n";

    Future versions could try to parse the header to look for its end rather
    than insisting that the printed version match the version returned by
    header(). Patches would be very welcome.

SEE ALSO
    CGI::Compress::Gzip depends on CGI and IO::Zlib. Similar functionality
    is available from mod_gzip, Apache::Compress or Apache::GzipChain,
    however all of those require changes to the webserver configuration.

AUTHOR
    Chris Dolan

    This module was originally developed by me at Clotho Advanced Media Inc.
    Now I maintain it in my spare time.

ACKNOWLEDGMENTS
    Clotho greatly appreciates the assistance and feedback the community has
    extended to help refine this module.

    Thanks to Rhesa Rozendaal who noticed the -Type omission in v0.17.

    Thanks to Laga Mahesa who did some Windows testing and experimentation.

    Thanks to Slaven Rezic who 1) found several header handling bugs, 2)
    discovered the Apache::Registry and Filehandle caveats, 3) provided a
    patch incorporated into v0.17, and 4) persisted with smoke tests that
    reproduced the envvar problem fixed in v0.23.

    Thanks to Jan Willamowius who found a header handling bug.

    Thanks to Andreas J. Koenig and brian d foy for module naming advice.

HELP WANTED
    If you like this module, please help by testing on Windows or in a
    `FastCGI' environment, since I have neither available for easy testing.

    Personally, I don't use this module much anymore as all of my work is on
    Catalyst and mod_perl now.

