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.
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.
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
// 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
css // where are your css files (with or without subfolders)
cache // chomd 777, where will be cached parsed required files
With a script tag like this one:
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
'GzOutputClassFile' => 'php/classes/GzOutput.class.php', // relative GzOutput class file folder
'GlobalCacheFolder' => 'cache', // relative cache folder*
'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
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:
RewriteRule ^/css/(.*) /bootstrap.php?$1|css [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:
That's all :-)