GzOutput Class Basic Documetation

2007/01/16 - Andrea Giammarchi


GzOutput class has different ways to be used.
Every public method is static and exits from application showing parsed sources.

The simplest way to use this class is the create method.
You can use them to create runtime a gzencoded version (if host supports them) of a generic string.
The type should be a text/javascript, a text/css, text/plain and even text/html; charset=UTF-8 or every other Content Type You need while the level should be a number from 0 to 9 (0 means no compression, 9 means better compression).
By default level is 9, best compression.

What does it do ?

Runtime compression of a single file or a list of files.
It can be drived from external files to created required file automatically.
This class doesn't use source "hand-made" compressors, just pack everything using fantastic gz algorithm then it's compatible with every kind of JavaScript, CSS or other files type and final size will be at least 5 times smaller than original, even with preserved code comments.
Both server and client will spend less bandwidth each minute using a dedicated etag to force browser cache when required code has been ust downloaded (and if gz is enabled, it will have a smaller size).

What are better methods to use quickly ?

You can choose at least two simple ways to produce cachable, compressed files: createFromFile and createFromCache

Both method uses gz compression and force cache when files are not updated, force download of new content every time one of required files has been changed.

Basic createFromFile method usage

This public static method accepts different arguments but can be drived quickly by an external "bootstrap.php" file.
For example, if You need to serve several css files You could put a copy of bootstrap.php file inside css filder. So a link like this one:

<link rel="stylesheet" href="css/bootstrap.css.php?base|tables|extra" media="screen" type="text/css" />

will produce automatically a single css file, using a bootstrap.php like that:

<?php // css/bootstrap.css.php
require '../classes/GzOutput.class.php';		// GzOutput.class.php
GzOutput::createFromFile(__FILE__, 'text/css', 'css');	// createFromFile static method
// Result:
//	single css file with css/base.css, css/tables.css and css/extra.css included

This method doesn't require a folder with chmod 777 and creates entire output only if one css file has been updated or if browser doesn't cache files (or didn't cache them before).
Every different folder should have a bootstrap.php file, to make generation safe for your php sources but please don't put bootstrap.php inside a folder that contains your php scripts, or malicious users should get your sources.

You could view other arguments configuration directly on souce code.

Basic createFromCache method usage

This public static method is the best choice both for your server and clients.
It uses a dedicated configuration with an associative array and file with them doesn't require to be present on each folder.
This method requires one folder with chmod 0x777 to create a caching system automatically.
Every cached file (note: not every client request) will produce a little report with some useful informations.

This is a simple host folders example:

root			// for example www.mydomain.com
	javascript	// where are your javascript files (with or without subfolder)
	css		// where are your css files (with or without subfolders)
	cache		// chomd 777, where will be cached parsed required files

Now suppose that You have 3 files inside javascript folder: library.js, init.all.js and other script inside another folder like extra/otherlibrary.js file.
With a script tag like this one:

<script type="text/javascript" src="/gzmanager.php?library|extra/otherlibrary|init.all|js"></script>

this method automatically create, if is not present inside cache folder, a single gz compressed script with preserved order:


So in this example your init.all.js file, the last of the list, can do everything because it will be the last piece of code of generated file.
The last uri value, js, is the extension to use with every file then You don't need to write file extension too, just remember that every name will be modified with choosed extension (so You can use css, html, others).

These informations are not changable from request uri because dedicated configuration file will filter every (I hope) malicious code injection.
This is an example gzmanager.php file:

// You can add or remove every "type" configuration but please don't change GzOutputClassFile and GlobalCacheFolder key names
$config = array(
	// * relative path from this file
	// (i.e. 'javascript' if this file folder has a "javascript" folder, '../javascript/' if folder is before than this one)
	'GzOutputClassFile'	=> 'php/classes/GzOutput.class.php',	// relative GzOutput class file folder
	'GlobalCacheFolder'	=> 'cache',				// relative cache folder*
	'JavaScriptInformations'=> array(				// JavaScript configuration
		'Folder'	=> 'javascript',			// relative JavaScript folder*
		'Extension'	=> 'js',				// JavaScript extension
		'Type'		=> 'text/javascript',			// JavaScript Content-Typ,
		'Comments'	=> '// (C) Andrea Giammarchi',		// JavaScript Comments
		'Compression'	=> 9,					// JavaScript Compression level (0 - 9)
		'Crunch'	=> 2					// JavaScript Crunch level (0 - 3)
	'CSSInformations'	=> array(				// CSS configuration
		'Folder'	=> 'css',				// relative CSS folder*
		'Extension'	=> 'css',				// CSS extension
		'Type'		=> 'text/css',				// CSS Content-Type
		'Comments'	=> '// (C) Andrea Giammarchi',		// CSS Comments
		'Compression'	=> 9,					// CSS Compression level (0 - 9)
		'Crunch'	=> 3					// CSS Crunch level (0 - 3)

// please don't modify these two lines
require $config['GzOutputClassFile'];

As You can see, accepted extension are defined inside this array then if last value doesn't match choosed extension, this method will not produce any kind of output.
At the same time, if one file is not present on dedicated folde, this class will produce a Not Found 404 HTTP 1.0 header.
If everything is correct, this method will check every modification date of choosed file, generates an etag and if this is not present verify if request has been done from other clients then get generated output (doesn't parse or modify them, just read) or creates them using choosed compression level, if Compression value is greater than 0 and after Cruncher parsing, if Crunch value is greater than 0.

Finally, You don't need to care about fies with same name, for example global.css and global.js, because generated cache file will be uniq for each request (and will be overwritten if file list is the same but one of them has been changed).
Isn't a simple, safe and fast client files solution ? I hope so.

What about Rewrite Rules ?

You can use an .htaccess file or modify mod_rewrite rules in different ways, for example:

RewriteEngine On
#RewriteBase /
RewriteRule ^/css/(.*) /bootstrap.php?$1|css [NE,R,L]
RewriteRule ^/javascript/(.*) /bootstrap.php?$1|js [NE,R,L]
RewriteRule ^/xhtml/(.*) /bootstrap.php?$1|html [NE,R,L]
RewriteRule ^/text/(.*) /bootstrap.php?$1|txt [NE,R,L]
RewriteRule ^/xml/(.*) /bootstrap.php?$1|xml [NE,R,L]

These are some urls examples:

// generated request: gzmanager.php?global|form|extra/labels|css
// returned css contents:
//			css/global.css
//			css/form.css
//			css/extra/labels.css

That's all :-)