Cache

Webasyst provides several PHP classes for caching data in several ways: in server RAM (runtime), in files, and additional caching options using memcached library or XCache accelerator.

Runtime cache

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');

Methods of waRuntimeCache class

• 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.

File caching

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 waSerializeCache and 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 .php extension.
• $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 waSerializeCache and waVarExportCache

The methods of these two classes are similar to those of waRuntimeCache class 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 'ttl' value;
• 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 [
    'default' => [    //use 'default' key for the default caching option
        'type' => 'memcached',    //required caching adapter key in lower case
        'namespace' => '...',   //arbitrary identifier to avoid conflicts of cache of several websites hosted on one server when memcached is used
        'prefix' => '...',   //arbitrary identifier to avoid conflicts of cache of several websites hosted on one server when XCache is used
        'servers' => [    //list of memcached servers
            [
                'host' => '',
                'port' => '',    //optional entry, defaults to 11211
                'weight' => '',    //optional entry, defaults to 0
            ],
            [
                ...
            ],
        ],
    ],
    'alternative' => [    //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' => [
        '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.

If file wa-config/cache.php is missing, then no alternative caching is used by default.

If file 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.:

wa('[app_id]')->getCache('alternative')

Methods of class waCache

• 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