C:/usr/local/lib/php/blueshoes-4.2/core/file/Bs_FileCache.class.phpandrej arn <andrej at blueshoes dot org>sam blume <sam at blueshoes dot org>Like a lot of other caches and still a little different.Typical Use :o You have just crunched data typically from a file using a lot of CPU and want topersist the crunched data for later use.Also you want to be notified if the persisted data has become 'out of date' becausethe 'origin-file' has changed AND/OR the lifetime you have set has passed.- (This is also referred as "Hot Update").USAGE Samples#################################################################################################### Sample 1# --------# Use with default settings.# Crunch only when the 'origin-file' file changes.# *1*) Create the cacher.$cacher =& new Bs_FileCache(); // Create new Cacher# *2*) Try to get the cached data using the file-path as key.$data = $cacher->fetch('D:/tmp/toCrunchData.txt');# *3*) Test the return value, FALSE is error, NULL is "out of date"if ($data === FALSE) { // ERRORecho "ERROR: " . $cacher->getLastError();} elseif ($data === NULL){ // "Out Of Date" (or not cached)// Crunch the data (Replaced with *YOUR* crunching function.)$crunchedData = myCruncher('D:/tmp/toCrunchData.txt');# *4*) Cache the data as serialized data$cacher->store('D:/tmp/toCrunchData.txt', serialize($crunchedData));} else { // SUCCESS$crunchedData = unserialize($data);}// do something with $crunchedData################### Sample 2# --------# Use with some property settings.# This time there is no 'origin-file' file and we use a 'lifetime' for the cache.# *1*) Create the cacher and set properties.$cacher =& new Bs_FileCache(); // Create new Cacher$cacher->setDir('r:/'); // TIPP: Use a RAM-Disk !$cacher->setBufferSize('200k'); // % of memory is also possible$cacher->setVerboseCacheNames(TRUE); // Give cache-files a readable name# *2*) Try to get the cached data using any key *you* define.$MY_CACHE_KEY = 'chachKey_1';$data = $cacher->fetch($MY_CACHE_KEY);# *3*) Test the return value, FALSE is error, NULL is "out of date"if ($data === FALSE) { // ERRORecho "ERROR: " . $cacher->getLastError();} elseif ($data === NULL){ // "Out Of Date" (or not cached)// Crunch the data (Replaced with *YOUR* crunching function.)$crunchedData = myCruncher('D:/tmp/toCrunchData.txt');# *4*) Cache the data as serialized data with timeout of 600s and disable 'origin-file' check$cacher->store($MY_CACHE_KEY, serialize($crunchedData), $originCheck=FALSE, 600);} else { // SUCCESS$crunchedData = unserialize($data);}###################################################################################################CONTEXT:To avoid confusion with the cache-mechanism used in this object keep in mind that'cache' : Is used to describe the data you want written to a persitent media (a file).'buffer': Is used to describe the data brought into memory as optimization to avoidreading from the file (second level cache).FEATURES :o Checks if 'origin-file' has changed AND/OR the lifetime you have set has passed(cache then becomes 'out of date').o Cache versioning to identify outdated/invalid cache data.*All* cache with older versions then $cacheVersion are considered 'out of date'.Very useful during development and updates, where the structure of the data yougenerate has changed and all cache data becomes invalid. Saves you the hassle todelete all old cache files spread all over the disk.o Exclusive cache writing to disk.o Second level memory buffer that holds the cache data in memory for reuse(Currently only until script ends).o setBufferSize() : Ability to set the memory buffer size in bytes OR in % of theavailable script memory.o setDir() : Define where you want the cache-files to be stored. 2 optionsa) In one central dirb) Below each 'origin-file' in a subdir.o setVerboseCacheNames() : Define if the 'cache-files' should contain a verbose name or not.A verbose name contains the name of the 'origin-file' (max first 100 chars).BASICS:Second level caching (memory buffered data):Stored or fetched data is kept in memory as a fifo-list.(Unless the data size is larger then the max allowed memory buffer size).If buffer is too full then the first entries of the fifo-list are removeduntil enough space is available and the new data is added to the end of the list.Entrys are valid only for a limited time (default is 10 secs. See setBufferLifetime()).Older entrys trigger the 'up to date'-check and are reloaded from cache when fetched (this incl. ).+---------------------------+Application | Memory buffer | Diskdata stream <---> | (second level cache) | <----> cache-file| organized as Fifo-List |+---------------------------+'Up To Date'-Checking :If in store() the parameter $originCheck===TRUE (default) it is assumed that thepassed 'data stream' has it's origin in a data file that was crunched (or parsedor whatever) and that the cache is valid as long as the 'origin-file' exists andis not modified.An 'Up To Date'-check compares the mod-time of the 'origin-file' against themod-time of the 'cache-file'. If'origin-file-time' <= 'cache-file-time'the cache is considered 'up to date'.The 'Up To Date' check takes place every time the 'cache-file' has to be loadedinto the memory buffer.dependencies: Bs_Dir, Bs_File, Bs_UnitConverterFile Cache Class.4.2.$id$bs4.1blueshoes.orgsting or int. Cache data with other version is considered invalid.NOTE to $cacheVersion use:*All* cache with older versions are considerd 'out of date'. Very usefull during developmentand updates, where the structure of the data you generate has changed and all cache databecomes invalid. Saves you the hassle to delete all old cache files spread all over the disk.Constructor.getLastModified()(unix timestamp in GMT!!)isModifiedSince() (unix timestamp in GMT!!)bool FALSE if not cached.the full path to the 'origin-file'.The cached data on success OR NULL if data is out of date.FALSE on all errors. Check getLastError().The $filePath is used in 2 ways :a) As key to identify the cache.b) See store()(If in store() you set: $originCheck==TRUE) the full path to the 'origin-file' is used to look up the mod-time.(If in store() you set: $originCheck==FALSE) $filePath is 'just' a key to identify the cach. No file look ups.Fetch the data stream that was once pushed into the cache.setCacheLifeTime()the full path to the 'origin-file'.the data to store.(default: TRUE) If we should check if the origin has modified. If FALSE don't even assume an existing origin file.(default: see above). The max lifetime in secs for this cache. 0 = forever. NULL (default) = use the setting from setCacheLifeTime(). if nothing was set using setCacheLifeTime() then it's 0 (which means forever).FALSE on all errors. Check getLastError().The $filePath is used in 2 ways :a) As key to identify the cache.b) (If $originCheck==TRUE) is the full path to the 'origin-file' to look up the mod-time.(If $originCheck==FALSE) *no* 'origin-file' is assumed, but $maxLifeTime should be setto a int > 0. If not it will default to 24 houres. You can set a default $maxLifeTimewith setCacheLifeTime() or indivitually by passing a parameter.The cache is considered 'out of date' (see fetch()) if one of following happens:a) $maxLifeTime has passed.b) The 'origin-file' changes (and $originCheck is set to TRUE)Done by comparing the modified times of the 'cache-file' and the 'origin file'as given by the parameter $filePath. If cache-file is eqal age oryounger, cache is considered 'up to date'Why the need for a max lifetime? You may think "we can check if the originalfile is older than the cache file, that's enough". lemme give you 2 reasons:1) If there is *no* origin file at all. That's the case when we cache somecalcuated data or something out of a database.2) The origin data, may it come from a real file or not, may include alifecycle. In my case the data is made up from an xml property file of aproduct in an eShop. Now that product may become alive or may become obsoletewithout that the original file changes, so that my crunching function comes up witha different result over time.Store the data stream to cache.the full path to the 'origin-file'.If the passed $filePath is not empty, the whole memory buffer is cleared.Otherwise only the entry matching $filePath is marked as invalid (if found)and will not be used any more. (That means it will reloaded from file)Clear the memory buffer (All or just one entry)kills all cached file content.(see above)The set buffersize in byte.FALSE on error. (Buffer size is left unchanged)Data that is sorted or fetched will be buffered up to the given size.When buffer is full the oldest entry(s) is kicked out.Default is 5% of the available memory as given by 'memory_limit' in the php.ini file.No buffering: If 'memory_limit' is not set or if you pass 0.Buffering with no limit: If you pass -1. (Of corse your not able to exceed PHP 'memory_limit')NOTE:It is possible that data of one entry is larger then the buffer limit.It will *NOT* be buffered then.PARAM:If numeric: We assume it as assumed to be absolute byte size.If string : May end with one of the usual unit endings e.g 'k', 'kb', 'M' (kilo-, mega-byte)If ending with '%' this means use x % of the available memory as given bymemory_limit in the php.ini file. But we never exceed 80%.Set the size of the cache buffersetCacheLifeTime()(default is 10s)on the 'origin'-file is fired. Only active if there is an 'origin'-file in use.If the 'origin'-file has changed since a fetch() will return the 'out of date'-value NULL.(More doc in header).The max time a memory buffered data is considered 'up to date' befor an 'up to date'-checksetBufferLifetime()(default is 0 == 'no lifetime check'). See above.hasn't changed. After this time a fetch() will return the 'out of date'-value NULL.Use if you want to limit the chache lifetime or when there is no 'origin'-file tocheck against (More doc in header).The max time until the cached data is considered 'out to date' even if the 'origin'-file(see above).If a valid path is passed all cache-files are stored in that dir. if the path does notexist yet, this method tries to create it.If called without param (or the dir is not writeable or not createable or whatever) asubdir called '_cache' will be created below the 'origin-file' dir and the cache-filesare stored there (default behavior, fallback too).Define where you want the cache-files to be stored.(see above).A verbose name contains the name of the 'origin-file' up to 100 chars.To keep the file unique, a md5-string is always appended to the chach-file.( The full path is taken to built the md5-string)Define if the 'cache-files' should contain a verbose name or not.If last public fuction had an error, a string is returned otherwise FALSE.Get last error.The index (see above)FALSE if not found.Find the index of the fifo-array matching $filePathA data chunckTRUE if add succeded, otherwise FALSEAdd $cacheBlock to fifo-arrayFree up the fifo-array until $sizeOfNewData fits in.Get rid of entries in the fifo-array that are marked invalidProblems solved here:a) If 'verboseName' is TRUE then include the origin-name into the cache name.b) If 'storeDir' is set all cache-files are stored in one dir and have to be unique.c) Unique file names are achieved by appending a md5-stringMake unique name with md5(abs.path/origin-file)Determine the cache-dir from the origin-dir and make the cache name.TRUE on success. FALSE Otherwise.FALSE on all errors. Check getLastError().It is assumed that the passed 'data stream' has it's origin in data file thatwas crunched (or parsed or whatever) and that the cache is valid as long asthe 'origin-file' exits and is not modified.An 'Up To Date'-check compars the mod-time of the 'origin-file' against themod time of the 'cache-file'. If'origin-file-time' <= 'cache-file-time'the cache is consitered 'up to date'.The 'Up To Date' check takes place every time the 'cache-file' has to be loadedinto the memory buffer.'Up To Date' - checking:FALSE on all errors. Check getLastError().Write cacheFALSE on all errors. Check getLastError().Read cacheSTATIC instance of Bs_File. gets instanced the first time in _writeCacheFile().array( 'maxCacheLifeTime' => 0, // <= Time (in secssetVerboseCacheNames()Internal cache propertiesarray()The second level cache as fifo list.NULL*All* cache with older versions are then 'out of date'. Very usefull during developmentand updates, where stucture of data you generate (and cache) has changed. Saves youthe hassel to go an delete all old cache files spread all over the disk.Use an int and increase it on every structure change. Set it in the constructor.The cache data has a version to identify outdated/invalid cache data.''$_errMsgHistorycontains the last error that occured and *is* reset after every *successfull* public function call.array()$_errMsgHistoryfor debugging. contains an error history that is *not* reset.array()4.0.$x$isexisexceptiontostringtohtmlpersistunpersistbs_objectbbsetoutputbbawakebbisawakebbxmsgbbxfunctionstartbbxfunctionendbbxechobbxvarbbxvardumpbbforcetracebbbufferstartbbbuffergetbbbufferendflushbbbufferendcleanbs_object_versionBs_ObjectBs_Object