^Status|Draft|
^Todo|Proof read|


====== Cache Library ======

Kohana lets you cache any data in order to achieve maximum performance.

The majority of web pages served today are generated dynamically, usually by an application server querying a back-end database. Caching consists in storing objects or pages in their fully rendered state so that they are directly loaded for next requests. It allows to cut response times and save server resources and memory.

**What should I cache?** Any objects or content requiring "heavy" dynamic generation.

Kohana's cache library can currently store caches in various containers including file and database. This is configurable by setting the driver. Cached objects or contents can be loaded using a powerful tag system or with their identifier.

For the API documentation:
  * not available yet

===== Configuration =====
Configuration is done in the ''application/config/cache.php'' file, if it's not there take the one from ''system/config'' and copy it to the application folder (see [[http://docs.kohanaphp.com/general/filesystem#cascading|cascading filesystem]]):
<code php>
$config['default'] = array(
  'driver' => 'file',
  'params' => APPPATH.'cache',
  'lifetime' => 1800,
  'requests' => 1000
);
</code>

=== Drivers ===

''config['driver']'' sets the driver, which is the container for your cached files. There are 6 different drivers:
  * File - File cache is fast and reliable, but requires many filesystem lookups.
  * SQlite - Database cache can be used to cache items remotely, but is slower.
  * Memcache - Memcache is very high performance, but prevents cache tags from being used.
  * APC - Alternative Php Cache
  * Eaccelerator
  * Xcache

=== Driver parameters ===

''$config['params']'' contains driver specific parameters. (in above example - path to server writable cache dir)

=== Cache Lifetime ===

''$config['lifetime']'' sets the lifetime of the cache (in seconds). Specific lifetime can be set when creating a new cache. 0 means it will never be deleted automatically

=== Garbage Collector ===

''$config['requests']'' average number of requests before automatic garbage collection begins. Set to a negative number will disable automatic garbage collection


===== How do I set up caching in my application? =====

Suppose you want to retrieve some information from your database and build a table of the entries you get. To cache the generated content, you would use in your controller code like this:

<code php>
$this->cache= Cache::instance();

$table = $this->cache->get('table');

if ( ! $table) {
    $table = build_table();
    $this->cache->set('table', $table, array('mytag1', 'mytag2'), 3600);
}

echo $table;
</code>

There are 3 main steps:
  * Instantiate the cache library
  * Get the cache:
    *  If the cache doesn't exist, we build the table by querying the database, we cache it for 1 hour (3600 seconds) for next requests and we print it.
    *  If the cache exists, we directly print the cached version of the table

===== Loading the library =====

<code php> $this->cache = Cache::instance();</code>

===== Methods =====

  * ''$this→cache→[[cache#set|set]]($id, $data, $tags = NULL, $lifetime = NULL)'' is used to set caches. 
  * ''$this->cache->[[cache#get|get]]($id)'' retrieves a cache with the given $id, returns the data or NULL
  * ''$this->cache->[[cache#find|find]]($tag)'' supply with a string, retrieves all caches with the given tag.
  * ''$this->cache->[[cache#delete|delete]]($id)'' deletes a cache item by id, returns a boolean.
  * ''$this->cache->[[cache#delete_tag|delete_tag]]($tag)'' deletes all cache items with a given tag, returns a boolean.
  * ''$this->cache->[[cache#delete_all|delete_all]]()'' deletes all cache items, returns a boolean.

==== Setting caches ====
=== set ===
''$this->cache->set($id,$data,$tags = NULL, $lifetime = NULL)'' is used to set caches. 

  * ''$id'' The id should be unique
  * ''$data'' If $data is not a string it will be serialized for storage. 
  * ''$tags''defaults to none, an array should be supplied.  This is useful when grouping caches together.
  * ''$lifetime'' specific lifetime can be set. If none given the default lifetime from the configuration file will be used.

<code php>
$data=array('Jean Paul Sartre', 'Albert Camus', 'Simone de Beauvoir');

$tags=array('existentialism','philosophy','french');
$this->cache->set('existentialists',$data,$tags);
</code>


==== Finding and getting caches====
=== get ===
''$this->cache->get($id)'' retrieves a cache with the given $id, returns the data or NULL

<code php>
print_r($this->cache->get('existentialists'));
//returns:
// Array ( [0] => Jean Paul Sartre [1] => Albert Camus [2] => Simone de Beauvoir )
</code>

=== find ===
''$this->cache->find($tag)'' supply with a string, retrieves all caches with the given tag.
<code php>

$food=array('French bread','French wine','French cheese');

$this->cache->set('food',$food,array('french'));

print_r($this->cache->find('french'));
//returns
//Array ( [existentialists] => Array ( [0] => Jean Paul Sartre [1] => Albert Camus [2] => Simone de Beauvoir ) [food] => Array ( [0] => French bread [1] => French wine [2] => French cheese) )
</code>

==== Deleting caches ====

There are several methods to delete caches

=== delete ===

''$this->cache->delete($id)'' deletes a cache item by id, returns a boolean
<code php>
$this->cache->delete('food');
</code>

=== delete_tag ===

''$this->cache->delete_tag($tag)'' deletes all cache items with a given tag, returns a boolean
<code php>
$this->cache->delete_tag('french');
</code>

=== delete_all ===

''$this->cache->delete_all()'' deletes all cache items, returns a boolean
<code php>
$this->cache->delete_all();
</code>

===== SQLite Driver Schema =====

If you use the SQlite driver to store the caches the table can be constructed with this query.

<code sql>
create table caches(
	id varchar(127),
	hash char(40),
	tags varchar(255),
	expiration int,
	cache blob);
</code>