blueshoes php application framework and cms            core_net
[ class tree: core_net ] [ index: core_net ] [ all elements ]

Class: Bs_UrlCache

Source Location: /core/net/http/Bs_UrlCache.class.php

Class Overview

Bs_Object
   |
   --Bs_UrlCache

URL Cache Class


Author(s):

Version:

  • 4.3.$Revision: 1.5 $ $Date: 2003/12/08 06:15:02 $

Copyright:

  • blueshoes.org

Variables

Methods


Inherited Variables

Inherited Methods

Class: Bs_Object

Bs_Object::Bs_Object()
Bs_Object::getErrors()
Basic error handling: Get *all* errors as string array from the global Bs_Error-error stack.
Bs_Object::getLastError()
Basic error handling: Get last error string from the global Bs_Error-error stack.
Bs_Object::getLastErrors()
Basic error handling: Get last errors string array from the global Bs_Error-error stack sinc last call of getLastErrors().
Bs_Object::persist()
Persists this object by serializing it and saving it to a file with unique name.
Bs_Object::setError()
Basic error handling: Push an error string on the global Bs_Error-error stack.
Bs_Object::toHtml()
Dumps the content of this object to a string using PHP's var_dump().
Bs_Object::toString()
Dumps the content of this object to a string using PHP's var_dump().
Bs_Object::unpersist()
Fetches an object that was persisted with persist()

Class Details

[line 143]
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 generated pages, ie pages that have content from a db, and the db does not change every few seconds.

features: 1) domain and protocol mapping 2) excludeMask/includeMask 3) ignoreCaseInPath/ignoreCaseInQuerystring/ignoreCaseInUsername 4) different caches for different users 5) default settings 6) automatic not-modified-since and other headers handling

1) domain and protocol mapping: ppl may call your sites like http://www.blueshoes.org http://blueshoes.org https://blueshoes.org http://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 ignored for caching. else if includeMask is set, only pages that match this regexp are 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=helloWORLD the 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 defaults are (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 will be stored in '/temp-path/http/www.domain.com/80/dir/_nobody_/'. '_nobody_' is the special 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 the same result; different cache for each user. if you store the session id in a cookie var, 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 exit echo $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 content in one var, just use ob_start() at the beginning of the content generation and ob_get_contents() at the end. and if you don't want to modify all your php scripts, 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 how it would behave tomorrow, or so. guess that would have to be implemented 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.pdf http://www.w3.org/Protocols/rfc2616/rfc2616.html section 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 caches section 14.29 (Last-Modified) is the most common validation method section 3.11 (Entity Tags) covers the extra validation method

dependencies: Bs_FileCache, Bs_Dir, Bs_Url, Bs_System




Tags:

pattern:  singleton: (pseudostatic)
access:  public
version:  4.3.$Revision: 1.5 $ $Date: 2003/12/08 06:15:02 $
copyright:  blueshoes.org
author:  Andrej Arn <at blueshoes dot org>


[ Top ]


Class Variables

$baseCacheDir =

[line 179]

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().




Tags:

see:  _getAbsoluteCacheDir()
access:  public

Type:   string


[ Top ]

$Bs_System =

[line 158]

reference to globally used pseudostatic system class.



Tags:

access:  public

Type:   object


[ Top ]

$Bs_Url =

[line 151]

reference to globally used pseudostatic url class.



Tags:

access:  public

Type:   object


[ Top ]

$cacheControl =  'private'

[line 228]

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.




Tags:

var:  cacheControl
access:  public

Type:   string


[ Top ]

$checkForErrors =  TRUE

[line 258]

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 the generated page. and we don't want to cache that and display it to everyone, agree?




Tags:

access:  public

Type:   mixed


[ Top ]

$checkRequest =  TRUE

[line 247]

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 the server has to do something based on the submitted data, well, ...

if that's the case with get for you too, then you better use includeMask/excludeMask.

behavior change: if a get requests uses params in the querystring, then we won't cache either. mabe change from bool to int, so we can set what to check for. if all get is cached, or only get without querystring params.




Tags:

access:  public

Type:   mixed


[ Top ]

$excludeMask =

[line 189]

see header of class for documentation.



Tags:

todo:  implement this one
see:  var $includeMask
access:  public

Type:   string


[ Top ]

$ignoreCaseInPath =

[line 269]

see header of class for documentation.

not set means: use systems default. on unix the path is case sensitive, on windows not.




Tags:

see:  vars $ignoreCaseInQuerystring, Bs_UrlCache::$ignoreCaseInUsername
access:  public

Type:   bool


[ Top ]

$ignoreCaseInQuerystring =  0

[line 284]

see header of class for documentation.

default is to treat the querystring case sensitive. and that's recommended in most cases.

  1. = don't ignore
  2. = ignore
  3. = ignore var names only
  4. = ignore var values only




Tags:

todo:  implement options 2 and 3.
see:  vars $ignoreCaseInPath, Bs_UrlCache::$ignoreCaseInUsername
access:  public

Type:   int


[ Top ]

$ignoreCaseInUsername =  FALSE

[line 292]

see header of class for documentation.



Tags:

see:  vars $ignoreCaseInPath, Bs_UrlCache::$ignoreCaseInQuerystring
access:  public

Type:   mixed


[ Top ]

$includeMask =

[line 198]

see header of class for documentation.



Tags:

todo:  implement this one
see:  var $excludeMask
access:  public

Type:   string


[ Top ]

$lifetimeSecs =  600

[line 210]

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.




Tags:

access:  public

Type:   mixed


[ Top ]



Class Methods


constructor Bs_UrlCache [line 323]

Bs_UrlCache Bs_UrlCache( )

Constructor.



[ Top ]

method cachePage [line 432]

bool cachePage( string $content, [int $lifetimeSecs = null])

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



Tags:

return:  TRUE (on success)
throws:  bs_exception
access:  public


Parameters:

string   $content  
int   $lifetimeSecs  

[ Top ]

method flushFileCache [line 539]

bool flushFileCache( [mixed $onlyThisFolder = TRUE])

kills cached file content.

note that $this->setUrl() needs to be called first.




Tags:

return:  (TRUE on success, FALSE on failure. you should not worry, i think.)
access:  public


[ Top ]

method getCacheBaseDir [line 626]

string getCacheBaseDir( )

returns the cache base dir, example: c:/winnt/temp/http/some.blueshoes.org/80/ so it's an absolute path, including scheme, host and port.

$this->setDir() needs to be called first.




Tags:

since:  bs4.4
see:  Bs_UrlCache::getCacheFilePath(), _getAbsoluteCacheDir()
access:  public


[ Top ]

method getCacheFilePath [line 579]

array getCacheFilePath( mixed $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 in the path is not there. because that path will be added to the basePath and there is already a 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=bar path: 'https/some.order.blueshoes.org/81/bill/dir/' file: 'file.class.php?query=blah&foo=bar'




Tags:

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


[ Top ]

method getErrorMessage [line 678]

string getErrorMessage( long $errCode)

Return a textual error message for a bs uc error code



Tags:

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


Parameters:

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

[ Top ]

method getLastModified [line 477]

int getLastModified( )

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



Tags:

return:  (unix timestamp in GMT!!)
see:  Bs_UrlCache::isModifiedSince()
throws:  bool FALSE if not cached.
access:  public


[ Top ]

method getPage [line 497]

mixed getPage( )

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



Tags:

return:  string on success; bool FALSE if the page is not cached, the cache has expired, or whatever.
access:  public


[ Top ]

method isEmptyGetRequest [line 518]

bool isEmptyGetRequest( )



Tags:

access:  public


[ Top ]

method isModifiedSince [line 465]

bool isModifiedSince( int $since)

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



Tags:

see:  Bs_UrlCache::getLastModified()
access:  public


Parameters:

int   $since   (unix timestamp in GMT!!)

[ Top ]

method isNotModified [line 381]

void isNotModified( )

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



[ Top ]

method isPageCached [line 488]

int isPageCached( )

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



Tags:

return:  (1 if it is, 0 if it has expired, -1 if it's not.)
todo:  all
access:  public


[ Top ]

method setUrl [line 338]

bool setUrl( [string $url = NULL])

sets the url to use for that object.



Tags:

return:  TRUE
throws:  bs_exception
access:  public


Parameters:

string   $url   (if not given then the url from the current http request will be used.)

[ Top ]

method treatHeaders [line 401]

void treatHeaders( [int $expireMinutes = 5])

sends expires and lastmod headers.



Tags:

access:  public


Parameters:

int   $expireMinutes   (default is 5. tells in how many minutes this page should expire *in the client*. set a negative number for no caching.)

[ Top ]


Documentation generated on Mon, 29 Dec 2003 21:13:16 +0100 by phpDocumentor 1.2.3