A PHP Developer’s Guide to Caching Data in Drupal 7

If there’s one thing in programming that drives me up the wall, it’s patterns that I use once every few months, such that I almost remember what to do but inevitably forget some key detail. Lately, that has been when I’ve needed to cache data from remote web services. I end up searching for A Beginner's Guide to Caching Data in Drupal 7 and checking it’s examples against my code. That’s no fun at all.

After some searching for a different project, I found the Drupal Doctrine Cache project and thought "what if I could chain the static and Drupal cache calls automatically?" - and of course, it’s already done with Doctrine’s ChainCache class. ChainCache gives us a consistent API for all of the usual cache operations. The class takes an array of CacheProvider classes that can be used to cache data. When fetching data, it goes through them in order until it finds the object you’re looking for. As a developer, caching data in memory in a static cache is no different than caching it in MySQL, Redis, or anything else. On top of that, ChainCache handles saving and deleting entries through the entire chain automatically. If you update the database (and invalidate your cached data), you can clear the static and persistent caches with a simple $cache->delete(). In fact, as someone using the cache object directly, you might not even know that a static cache exists! For example, the ChainCache could be updated to also persist data in a local APC cache. Or, the persistent Drupal cache could be removed if it turned out not to improve performance. Calling code doesn't need to have any knowledge of these changes. All that matters is you can reliably save, fetch, and delete cached data with a consistent interface.

What does all this mean? If you’re already using Composer in your Drupal projects, you can easily use these classes to simplify any of your caching code. If you’re not using Composer, this makes a great (and simple) example of how you can start to use modern PHP libraries in your existing Drupal 7 project. Let’s see how this works.

Adding Drupal Doctrine Cache with Composer

The first step is to set up your module so that it requires the Drupal Doctrine Cache library. For modules that get posted on drupal.org, I like to use Composer Manager since it will handle managing Composer libraries when different contributed modules are all using Composer on the same site. Here are the steps to set it up:

1. Install Composer if you haven’t installed it yet.
2. Create a Drupal module with an info file and a module file (I’ve put an example module in a sandbox).
3. In the info file, depend on Composer Manager: dependencies[] = composer_manager
4. Open up a terminal, and change to the module directory.
5. Run composer init to create your initial composer.json file. For the package name, use drupal/my_module_name.
6. When you get to the step to define dependencies (you can modify them later), add capgemini/drupal_doctrine_cache to require the library. You can add it later by editing composer.json or using composer require.

When you enable your module with Drush, Composer Manager will download the library automatically and put it in the vendor folder. For site implementations, it’s worth reading the Composer Manager documentation to learn how to configure folder paths and so on.

Using the CacheProvider for a Static and Persistent Cache

We’re now at the point where we can use all of the classes provided by the Drupal Doctrine Cache library and Doctrine Cache in our module. In a previous implementation, we might have had caching code like this:

  
function my_module_function() {
  $my_data = &drupal_static(__FUNCTION__);
  if (!isset($my_data)) {
    if ($cache = cache_get('my_module_data')) {
      $my_data = $cache->data;
    }
    else {
      // Do your expensive calculations here, and populate $my_data
      // with the correct stuff.
      cache_set('my_module_data', $my_data);
    }
  }
  return $my_data;
}
  

We can now replace this code with the ChainCache class. While this is nearly the same amount of code as the previous version, I find it much easier to read and understand. One less level of nested if statements makes the code easier to debug. Best of all, to a junior or non-Drupal PHP developer, this code doesn’t contain any "Drupal magic" like drupal_static().

  
function my_module_function() {
  // We want this to be static so the ArrayCache() isn’t recreated on each function
  // call. In OOP code, make this a static class variable.
  static $cache;
  if (!$cache) {
    $cache = new ChainCache([new ArrayCache(), new DrupalDoctrineCache()]);
  }

  if ($cache->contains('my_module_data')) {
    $my_data = $cache->fetch('my_module_data');
  }
  else {
    // Do your expensive calculations here.
    $my_data = 'a very hard string to generate.';
    $cache->save('my_module_data', $my_data);
  }

  return $my_data;
}
  

If the calling code needs to interact with the cache directly, it’s entirely reasonable to return the cache object itself, and document in the @returns tag that a CacheProvider is returned. Your specific caching configuration is safe and abstracted, avoiding sporadic drupal_static_reset() calls in your code.

Interfaces are the Future, and they’re Already Here

Even if you prefer the Drupal-specific version of this code, there’s something really interesting about how Doctrine, a small bit of glue code, and Drupal can now work together. The above is all possible because Doctrine ships a set of interfaces for caching, instead of just creating raw functions or concrete classes. Doctrine is helpful in providing many prebuilt cache implementations, but those can be swapped out for anything - including a thin wrapper around Drupal’s cache functions. You can even go the other way around, and tie Drupal’s cache system into something like Guzzle’s Cache Subscriber to cache HTTP requests in Drupal. By writing our code around interfaces instead of implementations, we let others extend our code in ways that are simply impossible with Drupal-7 style procedural programming. The rest of the PHP community is already operating this way, and Drupal 8 works this way as well.

Do you know about other PHP libraries that are great at working with Drupal 7’s core systems? Share them here by posting a comment below.