File: php-with-html-plus-Apache-Notes-howto.0.13.txt

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


Conteg with Static HTML Pages + Apache Compression Stats
-----------------------------   ------------------------

Overview
--------

There are situations where you wish to use PHP to both parse and deliver html disk files. PHP is
designed to do that very easily, but has one major downside: all the Content Negotiation (provided
by default by web-servers for static files) is lost.

This little help file is designed to indicate how to get those lost facilities back, using the Conteg
Class. The web-server setup for PHP (below) will use the Apache httpd.conf file. Apart from that, the
examples given will work with any setup.

This help-file will NOT explain any details of Conteg setup (other than Apache Notes) - please refer
to the other help-files for that info - but instead will restrict itself to:

	* Apache setup re: auto-appended & -prepended files (Apache + PHP)
	* Apache setup re: Apache Notes (Apache + Conteg)
	* Example PHP coding for append/prepend files (Conteg)



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)


By default, with static disk-bound files, most web-servers 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

With the appropriate switches, Conteg will restore those identical features. 

By default, Conteg auto-negotiates `Accept-Encoding' (load-balanced compression). By default, Apache
does NOT store compression stats within the log-file. Conteg contains switches which make it very
simple to instruct Apache to store this info (via the `Apache Notes' mechanism). This help-file will
also set out how to achieve that


Implementation - Overview
-------------------------

	1 Setup the web-server for auto-appended & -prepended files (+ compression stats for Apache)
	2 Use the auto-prepend PHP file to include Conteg
	3 Use the auto-append PHP file to setup Conteg


1 Setup the web-server
----------------------

# httpd.conf

# foll required to provide full `$_SERVER' variables
ExtendedStatus On

# foll required by some Apache2 users to obtain `PATH_INFO'
AcceptPathInfo = On

# setup auto-appended + -prepended files
# Check! - IfModule value may vary on your server
<IfModule mod_php4.c>
	AddType application/x-httpd-php .html
	php_value auto_append_file "/server/path/to/auto_append.php"
	php_value auto_prepend_file "/server/path/to/auto_prepend.php"
</IfModule>

# Info to put deflate stats into logs
# Note: (LogFormat) last 2 lines are best as one single line
DeflateFilterNote Input instream
DeflateFilterNote Output outstream
DeflateFilterNote Ratio ratio
LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\" In:%{instream}n \
Out:%{outstream}n:%{ratio}npct." deflate

# declare for logs
CustomLog logs/access_log deflate

# Use `apachectl graceful' (Command line) after these changes.


2 The auto-prepend file
-----------------------

<?php
	// -------------- auto-prepend file : top code --------
	ob_start();                       // Conteg requirement
	require_once( 'Conteg.include' );
?>


3 The auto-append file
-----------------------

<?php
	// -------------- auto-append file : bottom code --------
	if( !empty( $GLOBALS[ '_SERVER' ])) {
	   $_SERVER_ARRAY	= '_SERVER';
	} elseif( !empty( $GLOBALS[ 'HTTP_SERVER_VARS' ])) {
	   $_SERVER_ARRAY	= 'HTTP_SERVER_VARS';
	} else {
	   $_SERVER_ARRAY	= 'GLOBALS';
	}

	// this declaration causes auto-despatch of the file
	new Conteg( array(
	   'modified'         => filemtime( ${$_SERVER_ARRAY}[ 'PATH_TRANSLATED' ]),
	   'use_etag'         => TRUE,
	   'use_apache_notes' => TRUE
	));
	// any prog cleanup or end-processing goes here
	// careful not to cause any more output
?>


Notes: 1 There are other Conteg defaults which may need varying; see basic-howto.0.13.txt.
       2 The `DeflateFilterNote' values above are Conteg defaults, and may be varied by
        +means of the setup parameter (any, all or none); these are the defaults:
         - 'input'  => 'instream'
         - 'output' => 'outstream'
         - 'ratio'  => 'ratio'
       (Obviously, non of the above contains the coding    )
       (which will cause you to use PHP in the first place.)


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 02 March, 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/)