File: how-to.0.13.txt

Conteg v0.13 - Content Negotiation + Cache-Control for PHP-originated Web Output.


Basic Implementation
------------------

Introduction
------------

Conteg utilises the content-negotiation features of the HTTP protocol to:

	* Reduce bandwidth
	* Increase perceived (and actual) server responsiveness


The requirements are:

	* PHP 4.1.0+
	* zlib (for compression - odds are you have it)
	* `ExtendedStatus On' in httpd.conf (Apache) (re: $_SERVER-type variables)


With the appropriate switches, Conteg will auto-send the correct:

	* 304 Not Modified
	* 406 Not Acceptable
	* 412 Precondition Failed
	* 416 Requested Range Not Satisfiable
	* 206 Partial content, or
	* 200 OK page
	+ full headers
	  (404 + arbitrary status headers also available)

The simplest possible usage requires 3 lines of code and, by default, will:

	* Auto-negotiate load-balanced compression
	  - Accept-Encoding negotiation accommodates known browser foibles
	  - load-balancing currently works on Linux, FreeBSD only
	* Auto-switch according to HTTP protocol version
	* Send Content-Type, Charset, Content-Language + Expiry Response headers
	  - by default, 'text/html', 'ISO-8859-1', 'en' + 3600
	* Send Cache-Control headers to ensure full caching of content
	* Report Referer, Browser + OS-platform
	* Report a full range of Request headers


Implementation - One-Time Config
--------------------------------

 Before use: locate `$_num_cpu' and change to the number on *your* machine (default 1).


Implementation - Simplest
-------------------------

The following is copied from comments included with the Class:

 * How to use:
 *
 *  Simplest possible usage requires 3 lines:
 *    1 Turn Output Buffering on.
 *    2 Include the Class file.
 *    3 On the *very* last line create an instance of the Class.
 *
 *    ------------Start of file---------------
 *    |<?php
 *    | ob_start();            // <==== line 1
 *    | include('Conteg.inc'); // <==== line 2
 *    |
 *    |... the page ...
 *    |
 *    | new Conteg();          // <==== line 3
 *    |?>
 *    -------------End of file----------------
 *
 *  Things to note:
 *   1 The '<?php' tag MUST be the first characters of the file
 *   2 Likewise, the '?>' tag MUST be the final characters of the file.
 *    +Be careful of a space hiding there.
 *   3 Output buffering can be turned on in the main config file, in which
 *    +case line 1 above is optional.
 *   4 An auto_prepend_file is a possibility for `ob_start()' and an 
 *    +auto_append_file for `new Conteg()'.

If the defaults ('text/html', 'ISO-8859-1', 'en' + Expiry: 3600) are unsuitable for your site,
it will be necessary to either change them within the Class, or to move to the next usage level.


Implementation - Next Level
---------------------------

Here, either the supplied defaults are unsuitable or--more likely with any non-trivial usage
of the Class--the headers supplied for a specific page are anticipated to vary. The most obvious
(and important) example is the `Last-Modified' header - see below.

An array is available as a setup parameter to both the Class constructor (line 3 above) and 
`setup()' function. It is an array of `parameter-name' => `parameter-value' pairs.

The overview is to:
	1 Instantiate the Class early
	  - setup common-page defaults using the setup parameter
	  - include `no-print = TRUE' (default is `FALSE': print-on-declaration)
	2 Switch the Class defaults using `setup()' as required
	  - may be done at any time before send-page, and more than once
	3 At program end, use `show()' to send the page


The following pseudo-PHP will assume that `$mdate' is set to the page modified-date.

<?php
	ob_start();                            // Conteg requirement
	error_reporting( E_ALL );              // this is a test file
	include( 'Conteg.include' );

	$param     = array(
	   'noprint' => TRUE,                  //  default is show immediate
	   'expiry'  => 864000                 //  set expiry date 10 days from now for all pages
	);                                     //+ default is 1 hour
	$_Instance = new Conteg( $param );

	...
	(normal program flow)
	...

	// page-send
	$param = array(
	   'modified' => strtotime( $mdate )   //  ($mdate is string) default is time()
	);
	$_Instance->setup( $param );
	$_Instance->show();
	// any prog cleanup or processing goes here
	// careful not to cause any more output
?>


These are the most likely parameter values to be used (with defaults)
(a full list of 31 is included within the Class comments):

Accept-Encoding (load-balanced compression):
   'encodings'          => array( 'gzip','deflate','compress' ),
   'use_accept_encode'  => TRUE,

Last-Modified, Expiry + Cache-Control:
   'expiry'             => 3600,                            // secs after time()
   'modified'           => NULL,                            // sets $last_modified to time()
   'cache_control'      => array( 'macro' => 'cache-all' ), // many other values available
// 'cache_control'      => array( 'macro' => 'cache-none' ),

Charset, Language + Media-Type
(Note that, by default, these are reported but are NOT auto-negotiated):
   'charset'            => 'ISO-8859-1',
   'lang'               => 'en',
   'type'               => 'text/html',
   'use_accept'         => FALSE,
   'use_accept_charset' => FALSE,
   'use_accept_lang'    => FALSE,
   'use_content_lang'   => TRUE,
   'use_content_type'   => TRUE,

ETag, Ranges
(off by default; see also below):
   'etag'               => '',                              // external (strong) ETag
   'other_var'          => '',                              // extra string to affect (weak) ETag
   'use_accept_ranges'  => FALSE,
   'use_etag'           => FALSE,                           // both strong + weak OFF by default
   'weak_etag'          => TRUE


A Note on ETags
---------------

Strong ETags allow the use of `Accept-Range' (auto-negotiation of `If-None-Match', `If-Match',
`If-Range' + `Range'). Weak ETags allow auto-negotiation of `If-None-Match' + `If-Match'. The Class
default is for Weak ETags, since these are more commonly suitable for dynamic pages and content.

The following is from comments included with the Class:

 *    Strong ETags: 2 pages with the same ETag are byte-by-byte the same
 *    Weak ETags:   2 pages with the same ETag are *essentially* the same.
 *
 *    An example from modem-help.com is that the hit-counter, etc. may change,
 *   +but the rest of the content remains unchanged. If principal content changes
 *   +then the Modification Date is changed, which changes the (weak) ETag.
 *
 *    For Strong ETags the Class md5's the content, which can be slow on extremely
 *   +large files. An external ETag can be provided for these cases.

'other_var': The Class MD5's the following parameters to obtain a weak ETag:
-----------
             $this->_scriptName.
             $this->_port.
             $this->_query.
             $this->_session.
             $this->last_modified.
             $this->content_type.
             $this->content_lang.
             $this->_charset.
             $this->_other_var

(this is extremely quick).

`other_var' is a catch-all extra value to provide in those cases where some-other-feature(s)
of the page has changed, and to signal that to the User-Agent.


Some references
---------------

	*    HTTP/1.1:                  : http://www.w3.org/Protocols/rfc2616/rfc2616.html
	*    HTTP/1.0:                  : http://www.w3.org/Protocols/rfc1945/rfc1945.txt

	*    v0.13 release announcement : http://forums.modem-help.com/viewtopic.php?t=670
	*    v0.12.3                    : http://forums.modem-help.com/viewtopic.php?t=603
	*    v0.12.2                    : http://forums.modem-help.com/viewtopic.php?t=581
	*    v0.12.1                    : http://forums.modem-help.com/viewtopic.php?t=568
	*    v0.10                      : http://forums.modem-help.com/viewtopic.php?t=128


(c) Alex Kemp 28 February, 2007
website: http://www.modem-help.com/
(email address with-held due to historical/hysterical problems)
(contact instead via PM at http://forums.modem-help.com/)