Webasyst provides several PHP classes for caching data in several ways: in server RAM (runtime), in files, and additional caching options using memcached library and XCache accelerator.
For caching data in runtime, you may simply assign values to static variables in your code. But if your product is very complex or if you want to use a centralized method of accessing runtime cache, then you can use class
waRuntimeCache for this purpose. Each instance of this class corresponds to a static variable whose name is specified as a string parameter of the class constructor; e.g.:
//cache key must contain the ID of the app //which utilizes a cache variable $orders_cache = new waRuntimeCache('myapp_orders');
get(): obtain the value of the cache variable;
set($value): assign a value to the cache variable
delete(): deletion of the cache variable
isCached(): Boolean value denoting whether the cache variable exists.
For storing cache in files, save those files in
wa-cache/apps/[app_id]/ directory by avoiding cache files access conflicts with other apps and plugins.
For convenient access to cache files, use PHP classes
waVarExportCache. Each instance of these files corresponds to an individual cache file. The difference between these files is in the data storage format as explained below.
waSerializeCache stores the result of
serialize() function execution.
waVarExportCache stores the result of
var_export() function execution.
These files' constructors accept the following parameters:
$key: name of a cache file without
$ttl: optional integer value of the cache expiration period in seconds; defaults to -1, which means cache without an expiration period;
$app_id: ID of the app utilizing a cache file; defaults to the ID of the current app utilizing such a cache class instance.
Methods of classes
The methods of these two classes are similar to those of
waRuntimeCacheclass but they operate cache files rather than cached runtime values.
get(): obtain a cached value; cache file valitity is verified by comparing the difference between the current timestamp and the file saving timestamp towards the
set($value): write data to cache file including the
'ttl'value and the current timestamp;
delete(): delete cache file;
isCached(): check whether cache stored in the file is still valid.
Additional caching options
To enable caching by means of memcached or XCache, create configuration file
wa-config/cache.php with the contents similar to those shown in this example:
<?php return array( 'default' => array( //use 'default' key for the default caching option 'type' => 'memcached', //required caching adapter key in lower case 'servers' => array( //list of memcached servers array( 'host' => '', 'port' => '', //optional entry, defaults to 11211 'weight' => '', //optional entry, defaults to 0 ), array( ... ), ), ), 'alternative' => array( //if additional caching options are required, their configuration antries can be added with other, arbitrary, keys 'type' => 'xcache', //caching using XCache accelerator 'prefix' => ... //XCache prefix ), 'alternative2' => array( 'type' => 'file', //simple file caching in a directory different from the default one 'path' => '...', //path to custom cache storage directory different from the default path wa-cache/apps/ ), );
Using alternative caching options
To access the caching class waCache, call method
wa('[app_id]')->getCache(). Note that function
wa() should always be called with the ID of the app whose cache is being accessed; relying on the automatic calculation of the current app ID may cause ambiguous software operation.
wa-config/cache.php is missing, then no alternative caching is used by default.
wa-config/cache.php does exist, then method
wa('[app_id]')->getCache() by default returns an instance of the class corresponding to the caching adapter described in the
'default' configuration section. In the above example, the default caching adapter is the one utilizing memcached library.
It is a good habit to always check the value returned by method
wa('[app_id]')->getCache(). If a null value is returned then no further actions with the caching class make sense.
When it may be necessary in your product's source code, you may pass a string parameter when calling method
wa('[app_id]')->getCache() which should be one of the additional caching configuration keys, to use a different caching adapter instead of the default one; e.g.:
Methods of class
set($key, $value, $expiration = null, $group = null): saves a cache value
$key: key of cache value
$value: cache data
$expiration: non-negative integer value in seconds during which the specified cache value must be considered as valid; if no value of this format is specified, then the cached value is considered as valid regardless of the period of time passed since its saving to cache
$group: optional ID of the group used for organizing multiple cache entries
get($key, $group = null): returns a cached value
delete($key, $group = null): deletes a cached value
deleteGroup($group): deletes a group of cached values
deleteAll(): deletes entire cache of the current app