Cache API and caching tutorials

General introduction and tutorials

A good place to start is with Jeff Eaton's tutorial: A Beginner's Guide To Caching Data. It is a nice introduction on why and how to cache data.

Note the approach presented in the tutorial: the data is first cached statically for reuse within the same request, then cached on 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.

Note that because of a limitation of the api.drupal.org web site, you may not be able to view online the proper documentation of cache_set(), cache_get() and cache_clear_all(), because the site will return the documentation for the function declared in cache-install.inc instead of those of the same name declared in cache.inc as one would have expected. The former are empty shell functions, used during the installation process, while the latter are those you would normally 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.

What cache table to use?

If you are going to be caching 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.