Cache API overview

General introduction and tutorials

A good place to start is with Jeff Eaton's tutorial: A Beginner's Guide To Caching Data (2007) or A Beginner's Guide To Caching Data in Drupal 7 (2011). It is a nice introduction on why and how to cache data. Or, check the quick example below.

Note the approach presented in the tutorial: the data is first cached statically for reuse within the same request, then cached in the database for reuse across requests.

References

• All the cache API.
• cache_set(): this function is well documented and provides some more, useful documentation.
• cache_get() and cache_clear_all() are two more, useful functions to know and use.

Further information

What value to use for $cid?

The $cid (cache ID) uniquely identify a cached element in a {cache} table.

The $cid value doesn't matter -- you make your own (any string). You'll want to make it something that you can easily recreate when it comes time to cache_get the stored data. So your cid could be something like "foo_", $node->nid or whatever. Just take reasonable efforts to make sure that it will never collide with any other cid (if you're putting it in the cache table and not your own cache_foo table). Using a strategy like foo::id is probably fine.

If the cache holds translated strings, it should be made language aware. This is easily done by adding the global language code to the $cid.

What cache table to use?

If you are going to cache a lot of entries, it might be useful to create a separate cache table for your module to use (e.g. {cache_foo}).

If a certain piece data is highly perishable (i.e. if the date becomes obsolete quickly), you may want to cache it in the {cache_page} table: this is the default cache table. Many core modules (node, taxonomy, etc.) call cache_clear_all() without argument each time a node or a taxonomy term is added/edited/deleted. The whole {cache_page} table is then flushed.

Clearing obsolete data

As explained in Jeff's tutorial (above), the cache tables may be flushed at any time, so you must at all time be able to recreate the data from the information stored in other places in the database.

You decide when a piece of cached data is no longer relevant and then call cache_clear_all with the cid you want to clear. That's unless you decide to put your data in one of the core {cache} tables, and prefer to rely on synchronizing with the core modules and rely on them to clear the cache.

Development

Note that in good Drupal tradition, the API is constantly changing.

In Drupal 5 you should serialize and unserialize complex data structures when calling cache_get and cache_set. In Drupal 6 these structures will be recognized automatically and the un/serialization is handled by the cache API.

Example

function _my_function() {
  //works fine with D6 and D7
  if ($cache = cache_get('my_module_cache') && REQUEST_TIME < $cache->expire) {
    $data = $cache->data;
  }
  else {
    $data = 'xxxxxxx'; //do all your time taking complex calculations here
    cache_set('my_module_cache', $data, 'cache',  REQUEST_TIME  + (3600 * 24 * 30 * 6)); //stores in cache table and expires after 6 months
  }
  return $data;
}

Another Drupal 7 example using both drupal_static() and the cache system:

function mymodule_cached_data($reset = FALSE) {
  global $language;
  $langcode = $language->language;

  $data = &drupal_static(__FUNCTION__, NULL, $reset);

  if (!isset($data) || $reset) {
    if (!$reset && ($cache = cache_get("mymodule_cached_data:$langcode")) && !empty($cache->data) && REQUEST_TIME < $cache->expire) {
      $data = $cache->data;
    }
    else {
      $data = t('This would be an array or string generated using translated strings.');
      cache_set("mymodule_cached_data:$langcode", $data);
    }
  }
  return $data;
}

The function drupal_static() allows the results to be stored in internal memory without doing another database request for the cached data.