Blunt Cache

Blunt Cache is a persistent fragment and object chache for those of us that cannot use full page caching.

This plugin is meant for developers and requires code changes to your theme (and/or plugins). Please be sure to read the Documentation.

Fragment Caching

Capture and cache the HTML output of any section of code. Useful for storing HTML that is expensive to generate while leaving portions of the page that do not take much time or contain dynamic portions alone.

Object Caching

Capture and cache any object. Run a WP_query and cache the results. Store any variable that is time consuming to generate.

Most object caching scripts I’ve seen that override WP_Object_Cache are all or nothing, or require you to define what not to cache, I think. Seriously, I just find them a PITA to use. I don’t want to do complex configurations or coding to do something that should be really simple. This plugin will let you pick and choose what to cache persistantly without the hassle. Although this means that we can’t cache the main query, so it has its downside.

WP Transients API

Uses the WP Transients API to store cached objects and html fragments. This means that the cache data is stored in the options table in the DB and does require some queries. The small number of simple DB qureies used during the caching process should take less time.

Uses Filters and Actions

You use the cache by using apply_filters and do_action functions instead of calling functions of the plugin or instantiating a new object for every fragment and object to be cached. This means that you do not need to worry about checking to see that functions exist before you can use them. It also means that you can deactivate the plugin without worrying about your site breaking if you do. Need to do some work on the site and test, don’t want the cache to work while your doing it, just deactivate it, no files to remove.

Set Expirations

You can set the default experation time and the experation of individual fragments and object. Set the experation time for 1 second to… well… whatever floats your boat.

Unique Keys

You supply the unique key names for storing fragments and objects. Share the same fragments and objects in a single request or across mulitple requests, a single template file or multiple template files.

Clearing the Cache

Clear the entire cache at any time by adding ?blunt-query=clear to any url on your site.

Clear individual fragments or objects from the cache.

I have not added any mechanism to detect when items are updated or need to be cleared. I assume that you’ll know when you need to clear the cache or that you’ll write code that can use the action to clear individual fragments or objects when this needs to be accomplished. We’ll see how much use this gets. If there’s a lot of people using it then I’ll consider figuring out how to add something.

Cleans Up After Itself

Clearing the cache or deactivating this plugin will remove all transient data that it has created so you don’t need to worry about crap building up in you DB.

Works all by itself (almost)

No need to install any other caching plugin to make it work, but it does require adding code to your templates and/or plugins. This is not much different than the transient api.

Visit GitHub

Visit the GitHub repo for this plugin.

Add to Themes and Plugins

Safe to add to themes and plugins, does its own checking to see if another instance of Blunt Cache is already running.

Documentation

This plugin is not for those that are already using another caching system or plugin.

This plugin is for developers that need or want to decide what is cached when and for how long.

Standard Variables
The following variables are used throughout this documentation:

• $key = A unique key value for the fragment or object to be cached.
• $ttl = Time to Live or Experation Time. The time in seconds that a fragment or object should be stored before it expires. $ttl is an optional parameter in all of the code below. If you do not specify $ttl then the default $ttl value will be used.
• $type = The type of object. Valid values are “Fragment” and “Object”.
• $object = An object to store in the object cache.

A Note About Unique Keys

You can pass any string value as a key for your fragment of object. The actual key used to store your object will be an MD5 hash generated from your key value. This ensures that the key is both the correct length and that it is safe to use for a key value.

Some Examples of Unique Keys to Use:

• A key for a fragment or object generated in a specific file: $key = __FILE__;
• The 3rd key generated in a specific file: $key = __FILE__.'-3';
• A key for a fragment or object generated for a specific URL: $key = $_SERVER['REQUEST_URI'];
• The 4th key generated for a specific URL: $key = $_SERVER['REQUEST_URI'].'-4';
• A key for a fragment or object generated in a specific file for a specific URL: $key = __FILE__.$_SERVER['REQUEST_URI'];
• The 2nd key generated in a specific file for a specific URL: $key = __FILE__.$_SERVER['REQUEST_URI'].'-2';

Set Default $ttl

The built in default $ttl value is 3600 (1 hour). You can set the default $ttl value to whatever you’d like by including the following code in your function.php file, plugin, or whatever.

You should adjust this up depending on how much trafic you recieve on the site and how often you make changes. Low traffic sites or sites that are updated infrequently should have a longer time that the cache is valid for.

function set_blunt_cache_ttl($ttl) {
  $ttl = 60 * 60 * 6; // 6 hours
  return $ttl;
}
add_filter('blunt_cache_ttl', 'set_blunt_cache_ttl');

Fragment Cache

To store a fragment in the fragment cache:

$key = 'My Unique Key';
if (!apply_filters('blunt_cache_frag_check', false, $key)) {

  ////////////////////////////////////////////
  //  This HTML Output of this code block   //
  //  will be stored in the fragment cache  //
  ////////////////////////////////////////////

}
do_action('blunt_cache_frag_output_save', $key, $ttl);

Object Cache

To store an object in the object cache:

$key = 'My Unique Key';
if (($object = apply_filters('blunt_cache_get_object', false, $key)) === false) {

  $object = get_object();

  ////////////////////////////////////////////////
  //  Whatever $object is set to in this code   //
  //  block will be stored in the object cache  //
  ////////////////////////////////////////////////

  do_action('blunt_cache_object_save', $object, $key, $ttl);
}

Clearing Cache Values

Version 0.1.0 now includes automatic clearing of the cache and a mechanism for altering when the cache is automatically cleared. For backward compatibility the previous methods of clearing the cache have not been removed.

To remove a single item from the item cache

$type = 'fragment'; // or object
$key = 'My Unique Key';
do_action('blunt_cache_uncache', $type, $key);

To clear the entire cache

http://www.yoursite.com/?blunt-cache=clear

Setting automatic chache clearing. To determine when the cache is cleared you can add the following to your theme functions.php file.

define('BLUNT_CACHE_CLEAR_ACTIONS', 'admin_init');

The value of the constant should be a comma separeted list of WP hooks that will cause the cache to be cleared. If you do not define this constant then the default value is “admin_init” (as shown above). This means that the cache will be cleared on every admin page load. Please see Plugin API/Action Reference in the WordPress Codex for more information.

If the value of this constant evaluates to false (NULL, false, an empty string or 0 [Zerow]) then the cache will never be automatically cleared as the same way that it worked before.

You can set the cache to clear on any valid WP hook.