Get the files

You can download a zip file and extract it

OR

if you use a version control client you can checkout the sources of the project. It will make it easier to keep the files up to date.


Git clone

Checkout sources with git client.
The following commands create a directory ahcache below webroot and put all files there:

cd [webroot-directory]/[install-dir]/
git clone https://github.com/axelhahn/ahcache.git [optional-name-of-subdir]

Leaving [optional-name-of-subdir] empty will create a subdir named "ahcache"

Download


Get the latest version:
Download

Extract the 2 .*php files somewhere below webroot on your webserver. You can put to any subdirectory. It is not a must to have it in the webroot.


Basics: fill, read and renew the cache

  • Load the class file with include_once/ require_once
  • init the class with
    • name of your application or module
      In the background the class creates a subdirectory of that name in the cache directory. The several modules can use the same ID without conflict. And it is easy to delete all cached items if an application.
    • an ID for your data
      This ID can be a text or an integer. If you want to cache a RSS feed it can be the url of the feed; for database querys it can be the id of the requested item.
  • The methods read() and write([data , [ttl in sec]]) read and write the cached data.



An essential question is: how long can I use a cache and when shall I renew it? There is no general answer that fits all. It depends on your needs or the kind of data.
Below you get code snippets to start: we initialize a cache item and write it if it does not exist or is too old. Otherwise we use the already cached data.

write cache without ttl

I start with the most simple variant:
We just store data. Without knowledge how log to keep it.
Therefor we use the method write([data]) (without the 2nd parameter for a ttl).
With the method getAge() then you get the age of the cached item in seconds. If the return is false then no data were cached yet.

write cache with a known ttl

Often we exactly know the time how long to cache some data. If we request http data we can check "pragma: cache" in the reponse header or in RSS Feeds there is a TTL value (it is in minutes).

Write your data with the method write([data], [ttl]). Sure still works getAge(), but additionally you can profit from other functions:

  • verify with isExpired() if the cache is expired (true/ false).
  • iExpired() get time in seconds how long cachefile is expired; negative values show how long it is still valid
  • getExpire() get unix timestamp when cache expires
  • getTtl() get ttl value of the current cache item
    
    $sContent=''; 
    $iTtl=60*5; // 5 min for ttl

    require_once("/php/cache.class.php"); 
    $myCache=new AhCache("my-module","ID"); 

    if($myCache->isExpired()) { 
        // Cache does not exists or is too old
        // here follows the code to generate the content
        $sContent=... 

        // ... and put it to the cache
        $myCache->write($sContent, $iTtl); 
    } else { 
        // read cached data
        $sContent=$myCache->read(); 
    } 
    // output
    echo $sContent;

compare cache with a reference file

Sometimes you have content based on another source file, i.e. a thumbnail of an image must be younger than the source image or if you generate detail pages based on an uploaded csv file then we need to update the detail page when the csv was renewed.
Such a referenced file must be readable locally by the webserver: it can be a file below webroot or any other local file outside webroot or a file on any mounted NFS/ iScsi/ ... filesystem.

require_once("/php/cache.class.php"); 
$sCsvFile="source.csv" 
 
$myCache=new AhCache("my-module","ID"); 
$sContent=$myCache->read(); // read the cached data
 
// compare the age of the cache with a reference file
if (!$sContent || !$myCache->isNewerThanFile($sCsvFile)) { 
 
    // here follows the code to generate the content
    $sContent=... 
 
    // ... and put it to the cache
    $myCache->write($sContent); 
}; 
 
// output 
echo $sContent;

Cleanup; delete cache

If you have any mechanism to create a file in your filesystem you always must be able to control and to delete it.

delete a single item

Initialize tis class with module and id. To delete this cache item then call the delete method.

    require_once("/php/cache.class.php");  
    $myCache=new AhCache("my-module","ID");  
    $myCache->delete(); // delete a single cache item

delete all items of a module

Initialize this class with module only. To delete all cached items older n seconds then call the delete method. This function does not care if a cached item is outdated or not. You should use an age that is older than the maximum age of any item.

    require_once("/php/cache.class.php");  
    $o=new AhCache("my-module");  // remark: init module without id
    $o->cleanup(60*60*24*1); // delete cachefiles of module "my-module" older 1 day

delete all items (of all modules)

Initialize this class without any module.
To delete *all* cached items set value "0" (OK, this is just an example)
You should use an age that is older than the maximum age of any item of all modules to cleanup the cache directory.

    require_once("/php/cache.class.php");  
    $o=new AhCache(); // remark: init without module
    $o->cleanup(0); // delete all cachefiles of all modules

A better usage for deleting all cache items is a cronjob that deletes all cache data once per day older 1 week.

make cache invalid

Since version 2.4 a file will be generated on module level:
[cache-dir]/[module]/__remove_me_to_make_caches_invalid__

If you delete this file - i.e. with an SFTP client after connecting to your hoster - then all cached entries for the given module (this feature works per module only) will be invalid.

This file will be recreated on the next cache usage.

This is a fast method if you don't want to delete all cache entries.







Copyright © 2009-2019 Axel Hahn
project page: GitHub (en)
Axels Webseite (de)
results will be here