Documentation
Class libraries
cache
The generation of some pages can put quite a load on the server because of their complexity or the compute time they require.
If the data displayed by the page remains valid for some period of time, it may be a good idea to save the page content in a cache and instead of recomputing it every time a user requests it, serves the saved result from the cache.
To let you tune up the performance of your application and alleviate the load on your server, toKernel implements a cache system and provides an interface in the form of a class library.
How does the caching work in toKernel
There is two ways for caching the content: 'File caching' and 'System Memcached'.
File caching
The cache directory located in .../application/cache/
This directory permissions should allow the web server to write in it.
Since the cache directory is defined at the application level, each application instance has its own cache directory.
System Memcached
This option uses system memcached and requires php memcache extension.
Caching process
When toKernel parses a GET request to the application, it will derive a page ID from the request. This page ID will then be used to find whether the cache holds a valid (i.e. not expired) copy of the page.
When running the application in HTTP mode, the application run() method will use the page ID to check the cache. If a valid copy of the page is found, it will then load that copy and send it back to the client.
Otherwise, it will transfer control to the main callable action in the requested addon. When this is done, the run() method will then store the produced output in a new file in the cache directory.
See also: Running an application in HTTP mode.
Cache configuration
The main configuration file .../application/config/application.ini has a [CACHING] section where some parameters can be set by the web site administrator.
cache_expiration=0
is the life time of the cache in minutes.
| Value | Description |
|---|---|
| 0 | (default value) means the caching mechanism is disabled |
| -1 | means the pages in the cache will never expire automatically. The application will have to explicitly manage the cached pages life time? |
| n | means the pages will be considered has expired (invalid) after n minutes |
cache_file_extension=cache
is the extension used for cache files.
This will allow your application put some other files in the same directory without interfering with toKernel's cache management as long as you don't touch files with that extension.
| Value | Description |
|---|---|
| cache_lib=memcache | Memcache - caching with memcache. System/Memcached and PHP Memcache extension required |
| cache_lib=filecache | File cache - caching to local file system. Will cache content as files into application/cache directory |
Memcached connection values
| Value | Description |
|---|---|
| memcache_host | Memcache host (default value: localhost) |
| memcache_port | Memcache port (default value: 11211) |
Methods of cache library
mixed clean_all()
In file caching mode
Deletes all the files found in the cache and returns the count of deleted files.Example:
$deleted_count = $this->lib->cache->clean_all();
In memcache caching mode
Deletes all the files and returns boolean.bool expired(string $file_id [, int $minutes = NULL])
Checks if the file with id $file_id exists in the cache for more than $minutes minutes.
If the second argument is omitted, the configured cache_expiration value is used.
If the file does not exist or is older than $minutes minutes, the method will return true and remove the file if it exists. Otherwise, it will return false.
This function is quite useful if an application needs to directly manage the cache. In this case, it is likely to set the default cache expiration to a high value and then force a given file to be erased if it is older than some other value.
mixed get_content(string $file_id [, int $minutes = NULL])
Returns the content of the file with id $file_id if a valid copy exists in the cache.
If the second argument is omitted, the configured cache_expiration value is used.
If the file does not exist or is older than $minutes minutes, the method will return false.
Otherwise it returns the file contents.
As for the expired function, automatic cleaning of the file is provided by this method. This property can be used to invalidate a cached copy of a page before its default expiration time.
object instance([array $config])
Return new (cloned) instance of cache object (library).
bool remove(string $file_id)
Removes the file with id $file_id from the cache file and return true if existed.
array stats()
Return statistics array of cache.
bool write_content(string $file_id, string $buffer [, int $minutes = NULL])
Saves the content of $buffer to a file with id $file_id in the cache and returns true if the file was saved successfuly, false otherwise.
If the third argument is provided and a file with the same id already exists in the cache and is not expired (i.e. is not older than $minutes minutes) the method will do nothing and return true.
Using manual caching
The automatic caching mechanism implemented by toKernel makes it easy to improve the application performance if the pages displayed have a contents that doesn't change too frequently. For example, your application may be designed to browse a catalog or some other kind of data that is updated on a weekly or even daily basis. Once the data base has been updated, the web site administrator will have to invoke an action that will reset the cache and the new data will start to be displayed and the new pages will be cached until the next update.
However, even in this case, there maybe pages that you don't want to be cached, because their contents is updated more frequently. This is where the before run hooks are handy and would allow you to change the cache settings before executing some particular pages to prevent them to be cached.
On the other hand, automatic caching occurs only for pages generated by a main callable action.
If you want the result of some widget to be cached, then you have not choice but to manually manage the widget caching. For example, if we have a 'page' addon with 'show_top_menu' action, we can force the html content of the widget to be cached and force that copy to be displayed, instead of loading it again.
public function show_top_menu() {
$cache_id = 'page.show_top_menu';
// Get content from cache if already exists
$buffer = $this->lib->cache->get_content($cache_id, -1);
// -1 is used to prevent the cached copy to be removed
// Cache exists and not expired, just output its content.
if($buffer !== false) {
echo $buffer;
return true;
}
// There is no cached data.
// Load view object and set result to $buffer
$view = $this->load_view('top_menu');
$buffer = $view->run();
// Write content to cache.
$this->lib->cache->write_content($cache_id, $buffer, -1);
echo $buffer;
return true;
}
Another example which works with file caching mode and uses subdirectory
// Create configuration array
$config = array (
'cache_expiration' => 5,
'subdirectory' => 'menu_items'
);
// Get instance of cache object
$c = $this->lib->cache->instance($config);
Where 'cache_expiration' => 5 means the cache expiration time is 5 minutes and the 'subdirectory' => 'menu_items' means this section of cache will be located in separated directory as /application/cache/menu_items/.
// Try to get content from cache if not expired.
$content = $c->get_content('top_menu');
if($content !== false) {
// Cached data exists and not expired.
echo $content;
return true;
}
// Generating menu...
$content = 'this is top menu';
// Write the content to cache
$c->write_content('top_menu', $content);
echo $content;
return true;
However when we using caching mechanism in toKernel framework, there are no difference between file caching and memcached, excepts the subdirectoriy setting for file caching. All functionality (usage) is same with methods and behavior.