jCache is a class to store any data in a cache system like memcache. It supports other kind of storage like files or a SQL database.

Note that jCache doesn't use jKVDb as a backend, but it could use it in next versions.

Configuration ¶

[jcache]
default = foo

[jcache:foo]
enabled = 1
driver = file
;  other parameters....

[jcache:mymemcache]
driver=memcache
ttl=360
enabled=1
servers = memcache_host1:11211,memcache_host2:11211,memcache_host3:11211

To store and read from the cache system, call one of the static methods of jCache.

• jCache::get($key): to retrieve the value corresponding to the given key.
• jCache::set($key, $value, $ttl): to store a new value or modify an existing value. $ttl is optional
• jCache::delete($key): delete the given key-value
• jCache::increment($key): increment the value. You can indicate also the value of the incrementation
• jCache::decrement($key): decrement the value. You can indicate also the value of the decrementation
• jCache::add($key, $value): to store a new value. return false if the key already exists
• jCache::replace($key,$value, $ttl): to change the value of the corresponding key. If the key doesn't exist, it returns false. $ttl is optional.
• jCache::garbage(): delete all expired keys
• jCache::flush(): delete all keys
• jCache::call($fn, $fnargs, $ttl): get the value corresponding to the function name/args. If it is not set, call the function $fn with arguments $fnargs, which should return a value. This value is then put into the cache.

All this static methods accept as last argument a profile. By default, the "default" profile will be used.

The HTTP protocol defines some headers for the browser to say how to store the resource (the web page), if the browser can use its local cache system or not. So the browser can know if it should do a request, or, if it have to do a request, it can indicate to the server informations about the cache status. In the server side, we can then know if we have to regenerate the resource, or if we can say that the browser must use the content in its cache. It then saves bytes and bandwidth.

Jelix 1.4 integrate some new methods in the class jResponse to manage easily the HTTP cache. These methods are available for all responses, so you can activate HTTP cache for HTML page, images, JSON content etc. Don't forget that the cache is client side, not server side.

There are two ways to manage the browser cache: cache by expiration and cache by validation.

Warning: in most of cases, except if you use the method setLifeTime with a private cache, the HTTP cache should be used only for content that is not personnalized. The content should not include private data for example. It may be stored by some proxies, and then served to all users, because proxies don't use cookies (session cookies) as discriminant characteristics to store cache.

Cache by expiration ¶

$rep->setExpires($date);

// or

$rep->setExpires(“+1 days”);

$rep->setLifeTime(3600); //1 hour in private cache

//or 

$rep->setLifeTime(600, true);// 10 minutes in shared cache

The cache by validation allows to use a more complex cache politic. The browser always ask the page to the server, but the server can decide to return the whole content of the resource, or to say to the browser that it can use its cache content.

So you have to decide in your controller, if you should return or not the content of the resource. To help you, there is a method, isValidCache, that will return you true if the cache stored in the browser is still valid. Give to this method, the date of the last modification of the resource ("Last-modified" HTTP header), or a token corresponding to the state of the resource ("Etag" HTTP header). So you have to retrieve this date or to calculate this token (a token can be any string, a md5 hash for example).

In the controller:

$dateLastModified = $foo->updated_at; // date of the last modification

if ($rep->isValidCache($dateLastModified)) {
   // the cache is ok, we stop here.
   return $rep;
}

// example with "Etag"
$etag = ... ; // generate the etag, corresponding to the state of the resource

if ($rep->isValidCache(null, $etag)) {
    // the cache has the same etag, we stop here
   return $rep;
}

// cache is not valid.
// generate the content here

The parameter expected by isValidCache is a date, representing by a jDateTime or DateTime object, or a string compatible with strtotime.