This documentation covers functionality of objects that use a class that is extended from WWW_Factory class. Methods and calls in this documentation can be used when building your Models, Views and Controller classes and their functionality.
Wave Framework comes with an extensive caching framework that is entwined throughout the system and the API. While cache handling on HTTP page and API requests is one of the core features of Wave Framework, then this functionality is also available for MVC objects in one way or another.
While not directly related to Wave Framework caching, the API also implements API command buffering. This means that the API tracks what API requests are made and with what input within a single HTTP request. Since API requests can be nested in Wave Framework, at times the same API call can be executed multiple times with the exact same input.
In order to lower the potential memory and processing power consumption with these repeated requests, API has an internal buffer that stores API call request results for every API call that is successfully made. This buffer is used only within the single HTTP request and is not transferred to subsequent requests. This helps the API to minimize the amount of processing it needs to do when the same API call is requested in multiple places (such as loading certain users account information) in multiple places in the same view within the same HTTP request.
At times it is necessary to clear this buffer, in case you are certain that the buffer might have changed and that other calls are made that should return a different result, but do not because of the buffer. For those cases it is possible to clear the API buffer with the following call:
$this->clearBuffer();
This call resets the API buffer to the state that it was at the start of the request. In other words: empty.
Wave Framework has multiple methods that can be called from within the MVC objects. This includes methods for saving a custom keyword in cache, tagging cache or removing tagged cache. There's even a function that can return the result from the previously known cache of the current API call.
Wave Framework usually stores cache in Filesystem in '/filesystem/' folder which has to be writable, together with all of its subfolders, on the web server. But some cache can also be stored in APC, if APC is supported on the server. Wave Framework deals with this automatically, though you can turn off APC in Configuration even when the server supports it.
In order to trust in cache and use it properly, you must also know how to disable it. Wave Framework cache system is technically out of the control of MVC objects and these objects have very minimal control over how they themselves are being cached. Sometimes though, it is necessary to make sure that the current execution is not cached, no matter what. This can be done with the following command:
// This disables cache of the current API call
$this->disableCache();
// It is possible to enable it again before the call returns a result
$this->disableCache(false);
This state is not final however, which is why it is always possible to re-enable caching, if requested, as shown in the above example.
This cache-disabling also happens automatically whenever State Messenger is used, but you can read more about State Messenger in its own documentation page.
You can use Wave Framework caching system to write your own variables into cache that can be used in other parts of the system. These methods are pretty simple. Here is an example of both setting cache, getting the value from cache and then unsetting the cache variable:
// Here we add a value, with key as an address, to cache
$this->setCache('my-key','my-cached-value');
// This returns that value from cache
$myCachedValue=$this->getCache('my-key');
// This does the same as above, but accepts only cache that is less than 60 seconds old
$myCachedValue=$this->getCache('my-key',60);
// This unsets that cache key from cache
$this->unsetCache('my-key');
Cache variables that are set in cache are accessible by any other Controller and API call in the system as long as they are set. You can also see how 'old' a cache variable is with the following request:
// Returns timestamp of the cache creation time in seconds
$cacheAge=$this->cacheTime('my-key');
This timestamp can be useful to determine if something should be regenerated again, or not.
It is possible to write cache tags in Wave Framework. This means that it is possible to assign keywords, or 'tags', to any cache that the API creates. Multiple different caches can be stored under the same cache keyword.
Benefit of this type of cache tagging is that it is possible to delete cache in bulk based on these tags. Main situation where this would be useful is when you store a lot of cache for a specific product on your website - information that can take a long time to generate - and you wish to cache this information with a long expire time. But what if the product changes and cache is still not expired?
This is the type of situation where cache tags are useful. You can assign a tag to every cache that you create, and you can also make Wave Framework delete all cache that has been tagged with a specific keyword.
Here is an example, similar to the one shown in the previous section, about how to add a cache variable to cache, but this times together with a cache tag:
// Here we add a value, with key as an address, to cache, together with a cache tag
$this->setCache('my-key','my-cached-value','my-tag');
// Here is another cache value with a different key but the same cache tag
$this->setCache('my-other-key','my-other-cached-value','my-tag');
It is then possible to unset all cache that has that 'my-tag' set as the cache tag, all at once. Here's how:
$this->unsetTaggedCache('my-key');
After this method is called, then every cache in the system that has been tagged with 'my-key' would be deleted. This includes not just cache that has been written with setCache() methods, but also internal API calls as well as API calls that have been made over HTTP.
On a website or in a web service that is well built, it will be technically possible to cache most of your website and serve from cache almost every time with every HTTP request, only generating the data again if the system detects a change. This type of system is only possible with a well structured cache-tagged caching.
There is one more set of methods that is possible from within MVC Objects in Wave Framework that can be very useful at times. It is possible to refer to previous cache in Controllers. This means that if an API call is made and a Controller is loaded without cache being used, then this Controller can get both the timestamp and contents of cache of the previous time when the cache was there.
While a little difficult to explain, this flow description might give a good real life example:
Wave Framework however allows you to actually refer to the contents and timestamp of your previous cache and you can do with this data whatever you want within the Controller. You can even make the Controller return the previous cache every single time, which technically means that the first generated cache would be permanent.
This is how you can refer to the previous contents as well as the creation timestamp of the cache of the current API call:
// This returns the cache of the previous cache
$oldCacheContents=$this->getExistingCache();
// This returns the UNIX timestamp of the previous cache
$oldCacheTimestamp=$this->getExistingCacheTime();
These methods allow you to fine-tune details of your cache and architecture in general in order to build a more optimized and efficient software.
Wave Framework includes four different ways how cache can be stored on the server: filesystem cache, database cache, APC and Memcache. Caching is an important part of Wave Framework and is one of the better ways to improve the performance of your website.
You can define what type of caching you are using in your Configuration file. If APC, Memcache and Database cache options are not used, then Wave Framework uses Filesystem cache by default (thus it is not possible to turn off caching entirely). While you can set all caching options in Configuration file, then caching is used in the order of priority. Memcache is the fastest option in most cases, thus if this is used then other settings are ignored. Second is APC, then Database cache and then filesystem cache.
Please note that in most cases the filesystem cache is faster than database cache. Database cache is only provided as an option in case caching storage needs to be shared across servers.
Filesystem cache is used by default in Wave Framework. Filesystem stores its cache in '/filesystem/cache/' folder and its subfolders. Filesystem cache does not require additional configuration, the only thing that is needed is that the '/filesystem/' folders need to be writable by PHP.
Database cache is an alternative caching options for Wave Framework if APC and Memcache are not supported. Database cache allows to store cache in a database table. This database caching table should be in the same database that is defined in Configuration file.
To use database caching then you should turn on the 'cache-database' setting in Configuration and also define the connection settings. If connection settings are not set, then the main configuration settings are used for the connection.
Database caching assumes a single table with three columns that it uses for cache, here is the recommended database structure (with the default table name 'cache' and their columns):
APC caching has two benefits for any PHP system. APC allows to cache 'compiled' PHP scripts, thus giving an average performance speed increase of up to 80%. But APC also includes a simple storage of variables to cache. If 'apc' setting is set to 1 in Coniguration, then APC will be used as the storage engine for Data Handler and API Handler cache files.
Note that this type of caching stores two keys in APC, one for data and another for timestamp.
Memcache can strongly improve caching of a web service or a website. This is the recommended caching solution for most high traffic websites, but since PHP does not support it by default and it requires a separate server or service to be run, it is not an option on most hosting services (especially on shared hosting).
You can turn on Memcache by setting the value 'memcache' in Configuration file to 1. Note that this type of caching stores two keys in Memcache, one for data and another for timestamp.