Home » Caching » Cache_Lite » Manual

Introduction

Introduction – Introduction to Cache_Lite

Description

PEAR::Cache_Lite is a little cache system. It's optimized for high traffic websites so it is really fast and safe (because it uses file locking and/or anti-corruption tests).

Note : An independent documentation of Cache_Lite is available in chinese on this page.

Goals and technical details

speed

Before all, PEAR::Cache_Lite has to be extremely fast. That returns the use of PEAR possible on sites with high traffic without falling in hi-level hardware solutions.

You can find more details about cache_lite technical choices on this document, but the main idea is to include PEAR.php file ONLY when an error occurs (very rare).

simplicity

Because the cache system is often embedded in the application layer, PEAR::Cache_Lite kernel has to be small and flexible with an adapted licence (LGPL). Advanced functionality can be found in files that extend the core.

security

On high traffic websites, the cache system has to be really protected against cache files corruptions (because of concurrent accesses in read/write mode). Very few cache systems offer a protection against this problem.

File locking is not a perfect solution because it is useless with NFS or multithreaded servers. So in addition to it, PEAR::Cache_Lite offers two fully transparent mechanisms (based on hash keys) to guarantee the security of the data in all circumstances. Just have a look at the link given in the previous paragraph for more details.

Usage

general usage

Every module of Cache_Lite follows the same philosophy.

Parameters (others than default ones) are passed to the constructor by using an associative array.

A cache file is identified by a cache ID (and eventually a group). For obvious flexibility reasons, the logic of IDs choice is left to the developer.

In the following, we will use the term "group" as a pool of cache files and the term "block" as a piece of an HTML page.

core

Let's start with a simple example : the page is built, then recovered with a unique variable (string):

<?php

// Include the package
require_once('Cache/Lite.php');

// Set a id for this cache
$id = '123';

// Set a few options
$options = array(
    'cacheDir' => '/tmp/',
    'lifeTime' => 3600
);

// Create a Cache_Lite object
$Cache_Lite = new Cache_Lite($options);

// Test if thereis a valide cache for this id
if ($data = $Cache_Lite->get($id)) {

    // Cache hit !
    // Content is in $data
    // (...)

} else { // No valid cache found (you have to make the page)

    // Cache miss !
    // Put in $data datas to put in cache
    // (...)
    $Cache_Lite->save($data);

}

?>

If you wish use a cache per block and not a global cache, take as example the following script:

<?php
require_once('Cache/Lite.php');

$options = array(
    'cacheDir' => '/tmp/',
    'lifeTime' => 3600
);

// Create a Cache_Lite object
$Cache_Lite = new Cache_Lite($options);

if ($data = $Cache_Lite->get('block1')) {
    echo($data);
} else {
    $data = 'Data of the block 1';
    $Cache_Lite->save($data);
}

echo('<br><br>Non cached line !<br><br>');

if ($data = $Cache_Lite->get('block2')) {
    echo($data);
} else {
    $data = 'Data of the block 2';
    $Cache_Lite->save($data);
}

?>

core

However, it is not always possible to recover all the contents of a page in a single string variable. Thus Cache_Lite_Output comes to our aid :

<?php

require_once('Cache/Lite/Output.php');

$options = array(
    'cacheDir' => '/tmp/',
    'lifeTime' => 10
);

$cache = new Cache_Lite_Output($options);

if (!($cache->start('123'))) {
    // Cache missed...
    for($i=0;$i<1000;$i++) { // Making of the page...
        echo('0123456789');
    }
    $cache->end();
}

?>

The idea is the same for a per block usage :

<?php

require_once('Cache/Lite/Output.php');

$options = array(
    'cacheDir' => '/tmp/',
    'lifeTime' => 10
);

$cache = new Cache_Lite_Output($options);

if (!($cache->start('block1'))) {
    // Cache missed...
    echo('Data of the block 1 !');
    $cache->end();
}

echo('Non cached line !');

if (!($cache->start('block2'))) {
    // Cache missed...
    echo('Data of the block 2 !');
    $cache->end();
}

?>

IMPORTANT NOTE

For a maximum efficiency with Cache_Lite, do not systematically include every package the page needs. ONLY load the modules you need when the page is not in the cache (and has to be recomputed) by using a conditional inclusion.

The BAD way :

<?php
   require_once("Cache/Lite.php");
   require_once("...")
   require_once("...")
   // (...)
   $cache = new Cache_Lite();
   if ($data = $Cache_Lite->get($id)) { // cache hit !
       echo($data);
   } else { // page has to be (re)constructed in $data
       // (...)
       $Cache_Lite->save($data);
   }
?>

Here is the good way (often more than twice faster) :

<?php
   require_once("Cache/Lite.php");
   // (...)
   $cache = new Cache_Lite();
   if ($data = $Cache_Lite->get($id)) { // cache hit !
       echo($data);
   } else { // page has to be (re)constructed in $data
       require_once("...")
       require_once("...")
       // (...)
       $Cache_Lite->save($data);
   }
?>

Conclusion

To go further with Cache_Lite, have a look at examples and technical details bundled with the package.

constructor Cache_Lite::Cache_Lite

constructor Cache_Lite::Cache_Lite() – Constructor

Synopsis

void constructor Cache_Lite::Cache_Lite ( array $options = array(NULL) )

Description

The constructor of the Cache_Lite core class. You can give an associative array as an argument to set a lot of options.

Parameter

array $options

associative array to set a lot of options

Throws

No exceptions thrown.

Note

This function can not be called statically.

Example

Using most common options

<?php
require_once "Cache/Lite.php";

$options = array(
    'cacheDir' => '/tmp/',
    'lifeTime' => 7200,
    'pearErrorMode' => CACHE_LITE_ERROR_DIE
);

$cache = new Cache_Lite($options);

?>

Cache_Lite::get

Cache_Lite::get() – Test if a cache is available and (if yes) return it

Synopsis

string Cache_Lite::get ( string $id , string $group = 'default' , boolean $doNotTestCacheValidity = false )

Description

One of the main method of Cache_Lite : test the validity of a cache file and return it if it's available (FALSE else)

Parameter

string $id

cache id

string $group

name of the cache group

boolean $doNotTestCacheValidity

if set to TRUE, the cache validity won't be tested

Return value

returns data of the cache (or false if no cache available)

Note

This function can not be called statically.

Example

Usage

<?php
require_once "Cache/Lite.php";

$options = array(
    'cacheDir' => '/tmp/',
    'lifeTime' => 7200,
    'pearErrorMode' => CACHE_LITE_ERROR_DIE
);
$cache = new Cache_Lite($options);

if ($data = $cache->get('id_of_the_page')) {

    // Cache hit !
    // Content is in $data
    // (...)

} else {

    // No valid cache found (you have to make and save the page)
    // (...)

}

?>

Cache_Lite::save

Cache_Lite::save() – Save some data in a cache file

Synopsis

boolean Cache_Lite::save ( string $data , string $id = NULL , string $group = 'default' )

Description

save the given data (which has to be a string if automaticSerialization is set to FALSE (default)).

Parameter

string $data

data to put in a cache file (can be another type than strings if automaticSerialization is TRUE).

string $id

cache id

string $group

name of the cache group

Return value

returns true if no problem

Note

This function can not be called statically.

Example

Usage

<?php
require_once "Cache/Lite.php";

$options = array(
    'cacheDir' => '/tmp/',
    'lifeTime' => 7200,
    'pearErrorMode' => CACHE_LITE_ERROR_DIE
);
$cache = new Cache_Lite($options);

if ($data = $cache->get('id_of_the_page')) {

    // Cache hit !
    // Content is in $data
    echo $data;

} else { 
    
    // No valid cache found (you have to make and save the page)
    $data = '<html><head><title>test</title></head><body><p>this is a test</p></body></html>';
    echo $data;
    $cache->save($data);
    
}

?>

Cache_Lite::remove

Cache_Lite::remove() – Remove a cache file

Synopsis

boolean Cache_Lite::remove ( string $id , string $group = 'default' )

Description

remove the given cache file (specified with its id and group)

Parameter

string $id

cache id

string $group

name of the cache group

Return value

returns true if no problem

Note

This function can not be called statically.

Example

Usage

<?php
require_once "Cache/Lite.php";

$options = array(
    'cacheDir' => '/tmp/',
    'lifeTime' => 7200,
    'pearErrorMode' => CACHE_LITE_ERROR_DIE
);
$cache = new Cache_Lite($options);

$cache->remove('id_of_the_page');

if ($data = $cache->get('id_of_the_page')) {

    // Cache hit !
    // [IMPOSSIBLE !]

} else { 
    
    // No valid cache found (you have to make and save the page)
    $data = '<html><head><title>test</title></head><body><p>this is a test</p></body></html>';
    $cache->save($data);
    
}

?>

This is a dummy example because the cache is destroyed at the beginning of the script ! So the first case of the if statement is impossible.

Cache_Lite::clean

Cache_Lite::clean() – Clean the cache

Synopsis

boolean Cache_Lite::clean ( string $group = false , string $mode = 'ingroup'; )

Description

if no group is specified all cache files will be destroyed ; else only cache files of the specified group will be destroyed

Parameter

string $group

name of the cache group

string $mode

flush cache mode : 'old' (clean too old cache files for the current lifetime), 'ingroup' (clean all cache files for the given group), 'notingroup' (clean all the cache files except for the given group), [since 1.5.0 beta] 'callback_myFunc' (call the function 'myFunc' with the complete path file and the group in parameters, if the callback return 'true', the cache file is deleted).

Return value

returns true if no problem

Note

This function can not be called statically.

Example

Usage

<?php
require_once 'Cache/Lite.php';

$options = array('cacheDir' => '/tmp/');
$cache = new Cache_Lite($options);

$cache->clean();

?>

This example cleans all of the cache files.

Cache_Lite::setToDebug

Cache_Lite::setToDebug() – Set to debug mode

Synopsis

void Cache_Lite::setToDebug ( )

Description

when an error is found, the script will stop and the message will be displayed (in debug mode only) ; same effect than pearErrorMode option in the constructor

Note

This function can not be called statically.

Cache_Lite::setLifeTime

Cache_Lite::setLifeTime() – Set a new life time

Synopsis

void Cache_Lite::setLifeTime ( int $newLifeTime )

Description

change the cache life time

Parameter

integer $newLifeTime

new life time (in seconds)

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Cache_Lite::saveMemoryCachingState

Cache_Lite::saveMemoryCachingState() – Synopsis require_once 'Cache/Lite.php'; void Cache_Lite::saveMemoryCachingState ( string $id , string $group = 'default' ) Description save the current state of the memory caching array into a classical cache file Parameter string $id cache id string $group name of the cache group Note This function can not be called statically.

Cache_Lite::getMemoryCachingState

Cache_Lite::getMemoryCachingState() – Synopsis require_once 'Cache/Lite.php'; void Cache_Lite::getMemoryCachingState ( string $id , string $group = 'default' , bool $doNotTestCacheValidity = false ) Description load a previously saved state of a memory caching array from a classical cache file Parameter string $id cache id string $group name of the cache group boolean $doNotTestCacheValidity if set to TRUE, the cache validity won't be tested Note This function can not be called statically.

Cache_Lite::lastModified

Cache_Lite::lastModified() – Return the cache last modification time

Synopsis

int Cache_Lite::lastModified ( )

Description

[ONLY FOR CACHE_LITE HACKERS] return the cache last modification time

Return value

returns last modification time

Note

This function can not be called statically.

Cache_Lite::raiseError

Cache_Lite::raiseError() – Trigger a PEAR error

Synopsis

void Cache_Lite::raiseError ( string $msg , int $code )

Description

include dynamically the PEAR.php file and trigger a PEAR error

To improve performances, the PEAR.php file is included dynamically. The file is so included only when an error is triggered. So, in most cases, the file isn't included and perfs are much better.

Parameter

string $msg

error message

integer $code

error code

Note

This function can not be called statically.

Cache_Lite::extendLife

Cache_Lite::extendLife() – Extend the life of a valid cache file

Synopsis

void Cache_Lite::extendLife ( )

Description

[since Cache_Lite-1.7.0beta2] Extend the life of an existent cache file. The cache file is "touched", so it starts a new lifetime period. See this feature request for more details.

Throws

No exceptions thrown.

Note

This function can not be called statically.

Example

Classical use

<?php
require_once "Cache/Lite.php";

$options = array(
    'cacheDir' => '/tmp/',
    'lifeTime' => 7200,
    'pearErrorMode' => CACHE_LITE_ERROR_DIE
);

$cache = new Cache_Lite($options);
$id = 'foo';
if (!($data = $cache->get($id))) {
    // the cache is not hit !
    $data = '123456789';
    $cache->save($data);
} else {
    // the cache is hit !
    if (isset($_GET['extend'])) {
        $cache->extendLife();
    }
}
echo($data);

?>

constructor Cache_Lite_Output::Cache_Lite_Output

constructor Cache_Lite_Output::Cache_Lite_Output() – Constructor

Synopsis

void constructor Cache_Lite_Output::Cache_Lite_Output ( array $options )

Description

The constructor of the Cache_Lite_Output class. You can give an associative array as an argument to set a lot of options.

Parameter

array $options

associative array to set a lot of options (see Cache_Lite constructor for details)

Note

This function can not be called statically.

Cache_Lite_Output::start

Cache_Lite_Output::start() – Test if a cache is available and (if yes) return it to the browser. Else, the output buffering is activated.

Synopsis

boolean Cache_Lite_Output::start ( string $id , string $group = 'default' , boolean $doNotTestCacheValidity = false )

Description

Test if a cache is available and (if yes) return it to the browser. Else, the output buffering is activated.

Parameter

string $id

cache id

string $group

name of the cache group

boolean $doNotTestCacheValidity

if set to TRUE, the cache validity won't be tested

Return value

returns true if the cache is hit (false else)

Note

This function can not be called statically.

Example

classical using

<?php
require_once "Cache/Lite/Output.php";

$options = array(
    'cacheDir' => '/tmp/',
    'lifeTime' => 7200,
    'pearErrorMode' => CACHE_LITE_ERROR_DIE
);
$cache = new Cache_Lite_Output($options);

if (!($cache->start('id_of_the_page'))) {

    // Cache not hit !
    // All the output is bufferised until the end() method
    // (...)

    $cache->end();

}

?>

Cache_Lite_Output::end

Cache_Lite_Output::end() – Stop the output buffering started by the start() method and store the output to a cache file

Synopsis

void Cache_Lite_Output::end ( )

Description

Stop the output buffering started by the start() method and store the output to a cache file

Note

This function can not be called statically.

Example

Usage

<?php
require_once "Cache/Lite/Output.php";

$options = array(
    'cacheDir' => '/tmp/',
    'lifeTime' => 7200,
    'pearErrorMode' => CACHE_LITE_ERROR_DIE
);
$cache = Cache_Lite_Output($options);

if (!($cache->start('id_of_the_page'))) {

    // Cache not hit !
    // All the output is bufferised until the end() method
    // (...)
    
    $cache->end(); // the bufferised output is now stored into a cache file

}

?>

constructor Cache_Lite_Function::Cache_Lite_Function

constructor Cache_Lite_Function::Cache_Lite_Function() – Constructor

Synopsis

void constructor Cache_Lite_Function::Cache_Lite_Function ( array $options = array(NULL) )

Description

The constructor of the Cache_Lite_Output class. You can give an associative array as an argument to set a lot of options.

Parameter

array $options

associative array to set a lot of options (see Cache_Lite constructor for details). Be careful, with Cache_Lite_Function, additional options are available (comparatively to Cache_Lite). There are described on the following table.

Note

This function can not be called statically.

Cache_Lite_Function::call

Cache_Lite_Function::call() – Calls a cacheable function or method (or not if there is already a cache for it)

Synopsis

mixed Cache_Lite_Function::call ( string$functionName , mixed$arg1 , mixed$arg2 , mixed$arg3 , mixed... )

Description

call the given function with given arguments only if there is no cache about it ; else, the output of the function is read from the cache then send to the browser and the return value if read also from the cache and returned.

Return value

returns result of the function/method

Note

This function can not be called statically.

Example

classical using with a function

<?php

require_once('Cache/Lite/Function.php');

$options = array(
    'cacheDir' => '/tmp/',
    'lifeTime' => 3600
);

$cache = new Cache_Lite_Function($options);

$cache->call('function_to_bench', 12, 45);

function function_to_bench($arg1, $arg2) 
{
    echo "This is the output of the function function_to_bench($arg1, $arg2) !<br>";
    return "This is the result of the function function_to_bench($arg1, $arg2) !<br>";
}

?>

Example

classical using with a method

<?php

require_once('Cache/Lite/Function.php');

$options = array(
    'cacheDir' => '/tmp/',
    'lifeTime' => 3600
);

$cache = new Cache_Lite_Function($options);

$obj = new bench();
$obj->test = 666;

$cache->call('obj->method_to_bench', 12, 45);

class bench
{
    var $test;

    function method_to_bench($arg1, $arg2)
    {
        echo "\$obj->test = $this->test and this is the output of the method \$obj->method_to_bench($arg1, $arg2) !<br>";
        return "\$obj->test = $this->test and this is the result of the method \$obj->method_to_bench($arg1, $arg2) !<br>";        
    }
    
}

?>

If you try to use Cache_Lite_Function with $this object ($cache->call('this->method',...) for example), have a look first at the last example of this page.

Example

classical using with a static method

<?php

require_once('Cache/Lite/Function.php');

$options = array(
    'cacheDir' => '/tmp/',
    'lifeTime' => 3600
);

$cache = new Cache_Lite_Function($options);

$cache->call('bench::static_method_to_bench', 12, 45);

class bench
{
    var $test;

    function static_method_to_bench($arg1, $arg2) {
        echo "This is the output of the function static_method_to_bench($arg1, $arg2) !<br>";
        return "This is the result of the function static_method_to_bench($arg1, $arg2) !<br>";
    }
}

?>

Example

another using with a method (how to use cache $this->method() calls)

<?php

// Since Cache_Lite-1.7.0beta2

require_once('Cache/Lite/Function.php');

$options = array(
    'cacheDir' => '/tmp/',
    'lifeTime' => 3600
);

$obj = new foo($options);

class foo
{

    var $test;
    
    function foo($options)
    {
        $cache = new Cache_Lite_Function($options);
        $this->test = 'foobar';
        $cache->call(array(&$this, 'method_bar'), 12, 45);
    }
    
    function method_bar($arg1, $arg2)
    {
        echo "\$this->test = $this->test and this is the output of the method \$this->method_bar($arg1, $arg2) !<br>";
        return "\$this->test = $this->test and this is the result of the method \$this->method_bar($arg1, $arg2) !<br>";        
    }

}

?>

So, for method calls, the best way is to use array(&$object, 'nameOfTheMethod') as first argument instead of '$object->nameOfTheMethod' which doesn't work with "$this" for example.

Cache_Lite_Function::drop

Cache_Lite_Function::drop() – Drop a cache file

Synopsis

boolean Cache_Lite_Function::drop ( string$functionName , mixed$arg1 , mixed$arg2 , mixed$arg3 , mixed... )

Description

[since Cache_Lite 1.6.0beta1] Drop the cache file of the corresponding function call with given arguments.

Return value

returns true if ok

Note

This function can not be called statically.

Example

classical using with a function

<?php

require_once('Cache/Lite/Function.php');

$options = array(
    'cacheDir' => '/tmp/',
    'lifeTime' => 3600
);

$cache = new Cache_Lite_Function($options);

$cache->call('function_to_bench', 12,45);
$cache->call('function_to_bench', 12,45);

// clean the corresponding cache file
$cache->drop('function_to_bench', 12, 45);

function function_to_bench($arg1, $arg2) 
{
    echo "This is the output of the function function_to_bench($arg1, $arg2) !<br>";
    return "This is the result of the function function_to_bench($arg1, $arg2) !<br>";
}

?>

constructor Cache_Lite_File::Cache_Lite_File

constructor Cache_Lite_File::Cache_Lite_File() – Constructor

Synopsis

void constructor Cache_Lite_File::Cache_Lite_File ( array $options )

Description

The constructor of the Cache_Lite_File class. You can give an associative array as an argument to set a lot of options.

Parameter

array $options

associative array to set a lot of options (see Cache_Lite constructor for details). Be careful, with Cache_Lite_File, there is an additional "mandatory option" described on the following table.

Note

This function can not be called statically.

Cache_Lite_File::get

Cache_Lite_File::get() – Test if a cache is available and (if yes) return it

Synopsis

string Cache_Lite_File::get ( string $id , string $group = 'default' )

Description

test the validity of a cache file and return it if it's available (FALSE else)

Parameter

string $id

cache id

string $group

name of the cache group

Return value

returns data of the cache (or false if no cache available)

Note

This function can not be called statically.

Example

Usage

<?php
require_once "Cache/Lite/File.php";

$options = array(
    'cacheDir' => '/tmp/',
    'masterFile' => '/home/web/config.xml',
    'pearErrorMode' => CACHE_LITE_ERROR_DIE
);
$cache = new Cache_Lite_File($options);

if ($data = $cache->get('id_of_the_page')) {

    // Cache hit !
    // Content is in $data
    // (...)

} else { 
    
    // No valid cache found (you have to make and save the page)
    // (...)
    
}

?>