BlueShoes Application Framework - net/http

Bs_UrlCache

Bs_Object
|
+-- Bs_UrlCache

URL Cache Class

public class Bs_UrlCache extends Bs_Object

URL Cache Class
this is a web cache that links given url's to their cached output.kinda neat to break down server load for half-dynamically generatedpages, ie pages that have content from a db, and the db does notchange every few seconds.features:1) domain and protocol mapping2) excludeMask/includeMask3) ignoreCaseInPath/ignoreCaseInQuerystring/ignoreCaseInUsername4) different caches for different users5) default settings6) automatic not-modified-since and other headers handling1) domain and protocol mapping:ppl may call your sites likehttp://www.blueshoes.orghttp://blueshoes.orghttps://blueshoes.orghttp://blue-shoes.com...and in the end it's all the same content.so we need to map those to one.todo: that feature is not coded yet. but you can do similar things,check the doc inside the code in setUrl() for details.2) excludeMask/includeMask:if excludeMask is set, all url's that match this regexp (preg) are ignoredfor caching. else if includeMask is set, only pages that match this regexpare used for caching.3) ignoreCaseInPath/ignoreCaseInQuerystring/ignoreCaseInUsername:this is about upper case and lower case.look at this url: http://www.BLUEshoes.org/the/PATH/to/FILE.PHP?fooBAR=helloWORLDthe protocol and domain name (http://www.BLUEshoes.org) never matters.the path (the/PATH/to/FILE.PHP) matters on linux, not on windows.the querystring (fooBAR=helloWORLD) matters on all systems.for path and querystring you can set to treat them case insensitive. the defaultsare (see class vars): treat the path case sensitive on linux, but not on windows.the querystring is by default case sensitive on all systems. again, see class var.there may be a username/password in the url, like http://bill:gates@www.blueshoes.org/and if so, that username (bill) may be treated case insensitive aswell.4) if your url looks like 'http://www.domain.com/dir/file.php' then the cache file willbe stored in '/temp-path/http/www.domain.com/80/dir/_nobody_/'. '_nobody_' is thespecial user that means 'no-one'. but if your url is'http://bill:gates@www.domain.com/dir/file.php' then your path will be'/temp-path/http/www.domain.com/80/bill/dir/'.if your url includes the session id somewhere (no matter if it's a 3rd level domain,part of the path or part of the querystring) then you get a similar path with thesame result; different cache for each user. if you store the session id in a cookievar, you can still do it, just attach it to the url you pass to your UrlCache object.cause in the end the url is just a key.5) you can use this class by doing pretty nothing. see the examples below.6) header handling:deals with if-modified-since, expires, last-modified and cache-control headers.EXAMPLES:1) very basic example:$_urlCache =& new Bs_UrlCache();$_urlCache->setUrl();$pageContent = $_urlCache->getPage();if (is_string($pageContent)) {$_urlCache->isNotModified(); //may exitecho $pageContent;exit;} else {$_urlCache->treatHeaders(1);}//generate your page here, just like before$_urlCache->cachePage($yourPageContent);if you used echo etc everywhere and you don't have all generated page contentin one var, just use ob_start() at the beginning of the content generation andob_get_contents() at the end. and if you don't want to modify all your phpscripts, consinder using auto-prepend and auto-append scripts.2) using ob handler here//same script as in example 1, but without the cachePage() call. that comes here:ob_start();sleep(3);echo "this is your page content";include "antoherFile/that/outputs/content.php";$pageOut = ob_get_contents();ob_end_clean();echo $pageOut;$_urlCache->cachePage($pageOut);todo:- add the feature to set the timestamp of now. so we could see howit would behave tomorrow, or so. guess that would have to beimplemented rather in Bs_FileCache, and wrapped here.- add the feature to sort the querystring params, because:'file.php?foo=bar&hello=world' is the same as'file.php?hello=world&foo=bar'.additional reading:http://www.blueshoes.org/manual/Speed_matters.pdfhttp://www.w3.org/Protocols/rfc2616/rfc2616.htmlsection 13 (Caching)section 14.9 (Cache-Control header)section 14.21 (Expires header)section 14.32 (Pragma: no-cache) is important if you are interacting with HTTP/1.0 cachessection 14.29 (Last-Modified) is the most common validation methodsection 3.11 (Entity Tags) covers the extra validation methoddependencies: Bs_FileCache, Bs_Url, Bs_System

Authors

Version 4.0.$id$

Copyright blueshoes.org

Methods inherited from Bs_Object

isex, isexception, tostring, tohtml, persist, unpersist, bs_object, bbsetoutput, bbawake, bbisawake, bbxmsg, bbxfunctionstart, bbxfunctionend, bbxecho, bbxvar, bbxvardump, bbforcetrace, bbbufferstart, bbbufferget, bbbufferendflush, bbbufferendclean

Public Method Summary
void	Bs_UrlCache() Constructor.
bool	setUrl([ string $url ]) sets the url to use for that object.
void	treatHeaders([ integer $expireMinutes ]) sends expires and lastmod headers.
bool	cachePage(string $content, [ string $lifetimeSecs ]) caches the given content for the current url for lifetimeSecs seconds.
bool	isModifiedSince(int $since) wrapper method for Bs_FileCache->isModifiedSince() so look there.
int	getLastModified() wrapper method for Bs_FileCache->getLastModified() so look there.
int	isPageCached() tells if the current url is cached and if it has not expired yet.
string	getPage() fetches the cached page for the current url - if possible.
void	flushFileCache() kills all cached file content.
array	getCacheFilePath( $url) computes and returns the internal cache-file-path for the given url.
string	getErrorMessage(long $errCode) Return a textual error message for a bs uc error code

Private Method Summary
void	isNotModified() checks an incoming if-modified-since header and sends
void	_loadFileCache() loads the Bs_FileCache object.
string	_getAbsoluteCacheDir(string $domainPath) returns the absolute path to that cache directory.
void	&_raiseError([ string $code, string $msg, string $file, string $line, string $weight ]) returns a new exception (by reference).

Public Field Summary
object [unknown]	$Bs_Url reference to globally used pseudostatic url class.
object [unknown]	$Bs_System reference to globally used pseudostatic system class.
string	$baseCacheDir the drive and directory where the cache files are stored.
string	$excludeMask see header of class for documentation.
string	$includeMask see header of class for documentation.
integer	$lifetimeSecs the default lifetime in seconds. may be overwritten here,
string	$cacheControl how the page may be cached in the client.
string	$checkRequest checks that the http request was 'get'.
string	$checkForErrors checks that the to-cache page content does not have any php
bool	$ignoreCaseInPath see header of class for documentation.
integer	$ignoreCaseInQuerystring see header of class for documentation.
string	$ignoreCaseInUsername see header of class for documentation.

Private Field Summary
object [unknown]	$_bsFileCache instance of Bs_FileCache used for the caching backend.
string	$_url the full url that's in use. gets set in setUrl().
string	$_fileKey the file part we got from the url. gets set in setUrl().
unknown	$_cacheDir

Private Constant Summary
Bs_URLCACHE_VERSION	>>`4.0.$x$`<<	Warning: documentation is missing.
BS_UC_ERROR	>>`1`<<	Warning: documentation is missing.
BS_UC_ERROR_REQUEST_METHOD	>>`2`<<	Warning: documentation is missing.
BS_UC_ERROR_IN_OUTPUT	>>`3`<<	Warning: documentation is missing.
BS_UC_ERROR_NOT_CACHED	>>`4`<<	Warning: documentation is missing.
BS_UC_ERROR_CACHE_EXPIRED	>>`5`<<	Warning: documentation is missing.
BS_UC_ERROR_TMP_DIR	>>`6`<<	Warning: documentation is missing.

Public Method Details

Bs_UrlCache

public void Bs_UrlCache( )

Constructor.

Returns

void

setUrl

public bool setUrl( [ string $url ] )

sets the url to use for that object.

Parameter

string	$url	`= >>NULL<<`
	(if not given then the url from the current http request will be used.)

Returns

bool

TRUE

Throws bs_exception

treatHeaders

public void treatHeaders( [ integer $expireMinutes ] )

sends expires and lastmod headers.

Parameter

integer	$expireMinutes	`= >>5<<`
	(default is 5. tells in how many minutes this page should expire in the client. set a negative number for no caching.)

Returns

void

cachePage

public bool cachePage( string $content, [ string $lifetimeSecs ] )

caches the given content for the current url for lifetimeSecs seconds.

Parameter

string	$content

string	$lifetimeSecs	`= >>null<<`

Returns

bool

TRUE (on success)

Throws bs_exception

isModifiedSince

public bool isModifiedSince( int $since )

wrapper method for Bs_FileCache->isModifiedSince() so look there.

Parameter

int	$since
	(unix timestamp in GMT!!)

Returns

bool

getLastModified

public int getLastModified( )

wrapper method for Bs_FileCache->getLastModified() so look there.

Returns

int

(unix timestamp in GMT!!)

Throws bool FALSE if not cached.

isPageCached

public int isPageCached( )

tells if the current url is cached and if it has not expired yet.

Returns

int

(1 if it is, 0 if it has expired, -1 if it's not.)

getPage

public string getPage( )

fetches the cached page for the current url - if possible.

Returns

string

Throws bool FALSE if the page is not cached, the cache has expired, or whatever.

flushFileCache

public void flushFileCache( )

kills all cached file content.

Returns

void

getCacheFilePath

public array getCacheFilePath( $url )

computes and returns the internal cache-file-path for the given url.
takes the features "ignoreCase..." and "domain/protocol mapping" into account.examples:1) list($path, $file) = $this->getCacheFilePath('http://www.blueshoes.org/dir/file.php');now $path is 'http/www.blueshoes.org/80/dir/' and $file is 'file.php'. yes, the first slash inthe path is not there. because that path will be added to the basePath and there is alreadya trailing slash. if you wonder what the /80/ is, that's the port.2) a more advanced url example:https://bill:gates@some.order.blueshoes.org:81/dir/file.class.php?query=blah&foo=barpath: 'https/some.order.blueshoes.org/81/bill/dir/' file: 'file.class.php?query=blah&foo=bar'

Parameter

	$url
	Warning: documentation is missing.

Returns

array

(vector where element 0 is the path, element 1 the file name (with querystring).)

getErrorMessage

public string getErrorMessage( long $errCode )

Return a textual error message for a bs uc error code

Parameter

long	$errCode
	(a bs error code, see constants in header of that file.)

Returns

string

(error message, or false if the error code was not recognized.)

Private Method Details

isNotModified

private void isNotModified( )

checks an incoming if-modified-since header and sends
"304 - not modified" if possible, then exits the script.

Returns

void

_loadFileCache

private void _loadFileCache( )

loads the Bs_FileCache object.

Returns

void

_getAbsoluteCacheDir

private string _getAbsoluteCacheDir( string $domainPath )

returns the absolute path to that cache directory.

Parameter

string	$domainPath
	(element 0 of the result from getCacheFilePath().)

Returns

string

Throws bs_exception (that would be fatal, means cache not usable.)

&_raiseError

private void &_raiseError( [ string $code, string $msg, string $file, string $line, string $weight ] )

returns a new exception (by reference).

Parameter

string	$code	`= >>BS_DB_ERROR,<<`
	(error code, see definitions in top of file.)

string	$msg	`= >>NULL,<<`
	(textual error msg)

string	$file	`= >>''<<`
	(use __FILE__)

string	$line	`= >>''<<`
	(use __LINE__)

string	$weight	`= >>''<<`
	('fatal' etc.)

Returns

void

Public Field Details
$Bs_Url
public object [unknown] $Bs_Url >><< reference to globally used pseudostatic url class.

$Bs_System
public object [unknown] $Bs_System >><< reference to globally used pseudostatic system class.

$baseCacheDir
public string $baseCacheDir >><< the drive and directory where the cache files are stored. an example would be 'c:/tmp/'.if you don't set that, the systems default temp dir($APP['path']['tmp']) is used. see global getTmp().
See Also	_getAbsoluteCacheDir()

$excludeMask
public string $excludeMask >><< see header of class for documentation.
See Also	$includeMask

$includeMask
public string $includeMask >><< see header of class for documentation.
See Also	$excludeMask

$lifetimeSecs
public integer $lifetimeSecs >>`600`<< the default lifetime in seconds. may be overwritten here, or set as param in cachePage() on each call.after that time the page will be re-generated no matter what.

$cacheControl
public string $cacheControl >>`'private'`<< how the page may be cached in the client. one of:public => page may be cached in public, for example from a proxy-server,and then be served to different users. (dangerous!)private => page may be cached in client only (default here).no-cache => page may be cached, but must be revalidated each time (if-modified-since).no-store => no caching at all. better use no-cache if you can.the servers use 'public' as default, but if you don't set anything, we use'private' as default.

$checkRequest
public string $checkRequest >>`TRUE`<< checks that the http request was 'get'. we don't want to cache 'head' and certainly not 'post' requests.well post could be done if not much data was posted, but if theserver has to do something based on the submitted data, well, ...if that's the case with get for you too, then you better useincludeMask/excludeMask.

$checkForErrors
public string $checkForErrors >>`TRUE`<< checks that the to-cache page content does not have any php errors in it (parse errors, warnings, ...).it could be that because of whatever, there was an error on thegenerated page. and we don't want to cache that and display itto everyone, agree?

$ignoreCaseInPath
public bool $ignoreCaseInPath >><< see header of class for documentation. not set means: use systems default.on unix the path is case sensitive, on windows not.
See Also	$ignoreCaseInQuerystring, $ignoreCaseInUsername

$ignoreCaseInQuerystring
public integer $ignoreCaseInQuerystring >><< see header of class for documentation. default is to treat the querystring case sensitive. and that's recommended inmost cases.0 = don't ignore1 = ignore2 = ignore var names only3 = ignore var values only
See Also	$ignoreCaseInPath, $ignoreCaseInUsername

$ignoreCaseInUsername
public string $ignoreCaseInUsername >>`FALSE`<< see header of class for documentation.
See Also	$ignoreCaseInPath, $ignoreCaseInQuerystring

Private Field Details
$_bsFileCache
private object [unknown] $_bsFileCache >><< instance of Bs_FileCache used for the caching backend.

$_url
private string $_url >><< the full url that's in use. gets set in setUrl().

$_fileKey
private string $_fileKey >><< the file part we got from the url. gets set in setUrl().

$_cacheDir
private unknown $_cacheDir >><<

Private Constant Details
Bs_URLCACHE_VERSION `define( Bs_URLCACHE_VERSION, >>4.0.$x$<< )` Case: default: case sensitive

BS_UC_ERROR `define( BS_UC_ERROR, >>1<< )` Case: default: case sensitive

BS_UC_ERROR_REQUEST_METHOD `define( BS_UC_ERROR_REQUEST_METHOD, >>2<< )` Case: default: case sensitive

BS_UC_ERROR_IN_OUTPUT `define( BS_UC_ERROR_IN_OUTPUT, >>3<< )` Case: default: case sensitive

BS_UC_ERROR_NOT_CACHED `define( BS_UC_ERROR_NOT_CACHED, >>4<< )` Case: default: case sensitive

BS_UC_ERROR_CACHE_EXPIRED `define( BS_UC_ERROR_CACHE_EXPIRED, >>5<< )` Case: default: case sensitive

BS_UC_ERROR_TMP_DIR `define( BS_UC_ERROR_TMP_DIR, >>6<< )` Case: default: case sensitive

PHPDoc 1.0beta

BlueShoes Application Framework - net/http

Bs_UrlCache

public class Bs_UrlCache extends Bs_Object

Methods inherited from Bs_Object

Public Method Summary

Bs_UrlCache()

setUrl([ string $url ])

treatHeaders([ integer $expireMinutes ])

cachePage(string $content, [ string $lifetimeSecs ])

isModifiedSince(int $since)

getLastModified()

isPageCached()

getPage()

flushFileCache()

getCacheFilePath( $url)

getErrorMessage(long $errCode)

Private Method Summary

isNotModified()

_loadFileCache()

_getAbsoluteCacheDir(string $domainPath)

&_raiseError([ string $code, string $msg, string $file, string $line, string $weight ])

Public Field Summary

$Bs_Url

$Bs_System

$baseCacheDir

$excludeMask

$includeMask

$lifetimeSecs

$cacheControl

$checkRequest

$checkForErrors

$ignoreCaseInPath

$ignoreCaseInQuerystring

$ignoreCaseInUsername

Private Field Summary

$_bsFileCache

$_url

$_fileKey

$_cacheDir

Private Constant Summary

Public Method Details

Bs_UrlCache

setUrl

treatHeaders

cachePage

isModifiedSince

getLastModified

isPageCached

getPage

flushFileCache

getCacheFilePath

getErrorMessage

Private Method Details

isNotModified

_loadFileCache

_getAbsoluteCacheDir

&_raiseError

Public Field Details

$Bs_Url

$Bs_System

$baseCacheDir

$excludeMask

$includeMask

$lifetimeSecs

$cacheControl

$checkRequest

$checkForErrors

$ignoreCaseInPath

$ignoreCaseInQuerystring

$ignoreCaseInUsername

Private Field Details

$_bsFileCache

$_url

$_fileKey

$_cacheDir

Private Constant Details

Bs_URLCACHE_VERSION

BS_UC_ERROR

BS_UC_ERROR_REQUEST_METHOD

BS_UC_ERROR_IN_OUTPUT