Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
CGI::Compress::Gzip(3)User Contributed Perl DocumentatioCGI::Compress::Gzip(3)

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.

perl v5.24.1			  2017-07-03		CGI::Compress::Gzip(3)

NAME | LICENSE | SYNOPSIS | DESCRIPTION | CLASS METHODS | INSTANCE METHODS | CAVEATS | SEE ALSO | AUTHOR | ACKNOWLEDGMENTS | HELP WANTED

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=CGI::Compress::Gzip&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help