NAME

CGI::WebGzip - Perl extension for GZipping script output

SYNOPSIS

  # Usual code working with STDOUT:
  use CGI::WebGzip;
  print "Content-type: text/html\n\n";
  print "Hello, world!";

  # Lesser compression (by default 9, now - 5)
  use CGI::WebGzip(5);

  # Set callback function which would be called after compressing,
  # but before any output. You may set cookie in this function to
  # display them later on the page (using JavaScript).
  use CGI::WebGzip;
  BEGIN {
      CGI::WebGzip::setCallback(sub {
          my ($nL, $oL) = (length $_[0], length $_[2]);
          print sprintf "Set-Cookie: page_size=%d,%d; path=/\n", $oL, $nL;
          return 1;
      });
  }

  # Working together with CGI::WebOut.
  use CGI::WebGzip;
  use CGI::WebOut;
  print "Hello, world!";

  # Work in FastCGI environment.
  require CGI::WebGzip;
  while (read request) {
     CGI::WebGzip::import;  # captures output
     ...
     CGI::WebGzip::flush(); # releases output
  }

OVERVIEW

In PHP, you may write: ob_start("ob_gzhandler") and get all the output GZip-ed automatically. CGI::WebGzip does the same thing. Is you include this module in the beginning of your program, it whill capture all the output. When the script ends, CGI::WebGzip compresses captured data and send it to browser.

If browser is incompatible with GZip encoding, output will not be captured, and data will not be compressed.

DESCRIPTION

use CGI::WebGzip([compression_level])

Captures all the script output for deflating. Default compression level is 9 (maximum). Value 0 means no compression.

void flush()

Flushes the compressed buffer immediately and releases STDOUT capture. Usable in FastCGI environment together with manual import() call (see synopsis above).

bool getAbility()

Returns undef if we are in CGI mode, browser supports compression and Compress::Zlib is found. Otherwise returns non-empty diagnostic message.

bool isCompressibleType($type)

Returns true if page of this MIME type can be compressed.

CODE setCallback(CODE $func)

Sets the callback function called AFTER compression process, but BEFORE any output. You may print additional headers in this function (for example, set cookies). If this function returns false, compressed data would not be printed later (presume function does it itself). Arguments:

  bool callback(string $compressedBody, string $headers, string $originalBody)

Returns previous callback reference.

int setLevel($level)

Sets another compression level. Returns previous.

string getStatus()

You may determine if the compression was performed by this function. It returns undef if data has been compressed or non-empty diagnostic message otherwise.

($compressedBody, $modifiedHeaders, $status) ob_gzhandler(string $body [,string $headers])

Returns compressed data (additionally analysing headers, if present). In scalar context returns $compressedBody only. Input headers can be modified, thus this function returns $modifiedHeaders. In $status compression feruse message is returned (or undef if everything is OK). This function can be used exactly as PHPs ob_gzhandler().

string deflate_gzip($text, $level);

Compresses the input string and returns result.

EXPORT

None by default.

DEPENDENCIES

CGI::WebGzip depends on Compress::Zlib only. If this library is not found, no error messages are generated.

AUTHOR

Dmitry Koterov <koterov at cpan dot org>