Manual:CacheHelper

This page documents the class and associated functionality, which is available from MediaWiki core since version 1.20.

Rationale
It happens reasonably frequent that you have an interface where you want to display some content that is expensive to obtain or compute. MediaWiki has a caching interface which can be used for this. However, this interface is rather low level and forces you to re-implement the same basic functionality on top of it again and again. The CacheHelper class and associated code aim to provide a solution which is efficient, consistent and easy to use.

Implementation
The functionality is implemented as a CacheHelper object which implement the ICacheHelper interface. This object supports caching of any type of value. To increase easy of usage in special pages and actions, each category has it's own class containing a CacheHelper and additional utilities that allow directly adding cached HTML to the output, notifying the user they are watching a cached interface and allowing the user to invalidate the cache. These are CachedAction and SpecialCachedPage.


 * CacheHelper: contains all the core logic and can be used pretty much any where where you need to cache a bunch of stuff and would like to do so in batch.
 * ICacheHelper: interface for everything implementing CacheHelper functionality.
 * SpecialCachedPage: SpecialPage holding a CacheHelper and implementing ICacheHelper.
 * CachedAction: FormlessAction holding a CacheHelper and implementing ICacheHelper.

CacheHelper
A CacheHelper object takes one or more callbacks that return the results you want to have cached. This is done via the  method, which returns the computed value.

Example:

In case the cache result is in the cache, you will get this cached value. If it's not, the value is freshly computed and kept track of in the object before it's returned.

You can add as many such cached values to the CacheHelper object. After you're done, you need to call the  method, which will combine all the values and stuff them into a single cache entry. This combining makes the whole process more efficient and also ensures that all values where computed at the same point, thus avoiding potential inconsistency issues.

Expiry
You can set the expiry of the cache via the  method. This can be an interval in seconds, or a unix timestamp.

The default is 3600.

Cache key
Often you need to be able to cache multiple variations of the same interface, for instance because you want to show different content to users with different rights, or have an option to show verbose output. The  method takes an array of values to be used as cache key.

This needs to be set correctly before the first call to.

CachedAction and SpecialCachedPage
These classes both contain a CacheHelper and build on top of it in the same way, so provide the same caching interface.

This is a complete example of a SpecialPage with a chunk of cached HTML and another cached value.

Cache notification and purge link
Caching is great, but sometimes users really want to get the latest value. MediaWiki articles have action=purge just for this. SpecialCachedPage and CachedAction come with a similar facility build in. Whenever a cached version is shown, the subtitle of the page will be set to something like "You are watching a cached version of this page which can be up to 30 minutes old. [view latest]". Where "view latest" is a link that after clicking will provide the user with a rebuild version of the page.

This behavior can be altered by overriding the  method. It's default implementation is as follows:

Expiry
Like with CacheHelper, you can set the expiry via.

Cache key
By default the cache key is constructed from the internal name of the SpecialPage or Action, plus the users language. You can change this by overriding the  method.

Example:

This leads to having a cache version not only varying on the variables described above, but also on any request arguments.

Disabling the cache
It's quite possible that in certain cases you do not want to cache at all. For instance when you have a page of which the content is dependent on many user preferences, caching might result into to big fragmentation. You could however still cache for anonymous users, which might very well be causing the most requests anyway. In such a case you want to be able to disable the cache for logged in users. This can be done via the  method.

Saving
Classes deriving from SpecialCachedPage will automatically save the cache after your code has been executed. Those deriving from CachedAction need to call save manually, just like when using a raw CacheHelper object.