AhCache :: Get started

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 long 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 write method with an additional 2nd parameter where you set a TTL value in seconds: write([data], [ttl], [reffile]).

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.
Since v2.8 you can use a 3rd parameter in the write method. Next to your data and the TTL set a filename with full path. 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.
write([data], [ttl], [reffile]).
The cache expires after the given TTL and if the TTL was reached it compares the timesamp of the cache item with the one of the given reference file. So the ttl has the function of a minimal caching time. Set it to zero to allow the comparison with the reference file only.

    
    $sContent=''; 
    $iTtl=60*5; // 5 min for ttl
    $sRefFile="/tmp/myTouchfile.txt"

    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, $sRefFile); 
    } else { 
        // read cached data
        $sContent=$myCache->read(); 
    } 
    // output
    echo $sContent;

This is the way in former versions and still works.
Using the method isNewerThanFile([reffile]) ignores the TTL an compares the timesamp of the cache item with the one of the given reference file.

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.

When is a cache invalid?

Let's have a closer look...

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 and strong method to let expire all cache entries. This overrides given TTL values and reference files.

Cache admin web ui

If you want to enable the cache admin then go to the src drectory and rename the "cache-admin.class-enabled.php.dist" to "cache-admin.class-enabled.php" (without .dist). This file is not used - it must jiust exist.

Then browse to the [url-of-cache-class]/admin/cache-admin.php.