Writing WP Super Cache Plugins

WP Super Cache is a full page caching plugin for WordPress. When a page is cached almost all of WordPress is skipped and the page is sent to the browser with the minimum amount of code executed. This makes the page load much faster.

Unfortunately if you want to run code on every page load you're out of luck as regular WordPress plugins are not loaded or executed. You'll need to write a WP Super Cache plugin. This short introduction will not teach you how to write plugins but the example plugins that ship with WP Super Cache will get you a long way towards understanding how they work.

Before you get started writing a plugin you should be aware that you should not use the wp-super-cache/plugins/ directory. Every time WP Super Cache is updated this directory is deleted. So, edit your wp-config.php and set $wp_cache_plugins_dir to another directory where you'll put your plugin.

Chronology of a request

1. Request is received by WordPress.
2. WP_CACHE is defined and WordPress loads wp-content/advanced-cache.php.
3. That loads wp-cache-phase1.php or sets up error reporting if it's not found. wp-cache-phase2.php is also loaded.
4. WP Super Cache plugins are loaded.
5. The code checks if a cached file exists and serves it.
6. If no cached file, then it sets up a cache buffer and WordPress continues to load.
7. When the page is loaded, the plugin takes the buffer and writes it to a file.

Obviously there's a lot more than that there but looking through the code will give you a very good idea of what's happening.

Example from plugins/dynamic-cache-test.php

• dynamic_cache_test_init() hooks dynamic_cache_test_template_tag() on to the wp_footer action. dynamic_cache_test_filter() is hooked on to the wpsc_cachedata filter.
• An output buffer is created by WP Super Cache.
• Most of the page is generated by WordPress.
• The wp_footer action fires and the TAG is printed to the page.
• Processing continues and the page is created.
• The output buffer finishes. A WP Super Cache callback function runs and saves the output buffer to a cache file. The wpsc_cachedata filter is called.
• The function dynamic_cache_test_filter() runs and replaces the TAG in the buffer with the "Hello world" string.
• The output buffer is pushed to the browser to be displayed.

WP Super Cache ships with some example plugins in wp-super-cache/plugins/. Some of them even do useful tasks like help with domain mapping and Jetpack integration. There's one called "awaitingmoderation.php" which removes the text "Your comment is awaiting moderation." when someone writes a moderated comment. There's also dynamic-cache-test.php which is a complicated beast but it's heavily commented. It allows you to add template tags to your site that are replaced when the cached page is loaded.

These plugins run before most of WordPress has loaded. That means you can't rely on some of the nice features of WordPress such as filters and actions. However, WP Super Cache has it's own action/filter system that is similar to actions and filters in WordPress:

• add_cacheaction( $action, $func )
• do_cacheaction( $action, $value = '' )

A cacheaction is also a filter. If you hook on to a cache action that has a parameter, you must return that parameter at the end of the function like you would with a WordPress filter.

// from (from plugins/awaitingmoderation.php)
function awaitingmoderation_action( $buffer ) {
        $buffer = str_replace( __( 'Your comment is awaiting moderation.', 'wp-super-cache' ), '', $buffer );
        return $buffer;
}

function awaitingmoderation_actions() {
        global $cache_awaitingmoderation;
        if ( '1' === $cache_awaitingmoderation ) {
                add_filter( 'wpsupercache_buffer', 'awaitingmoderation_action' );
        }
}
add_cacheaction( 'add_cacheaction', 'awaitingmoderation_actions' );

If you need to hook into a WordPress filter use the imaginatively named cache action "add_cacheaction". That runs on "init" so the function that is executed can use add_action() or add_filter(). You can see this in action in the plugins/dynamic-cache-test.php or plugins/awaitingmoderation.php scripts.

Two very useful filters are the WordPress filter, "wpsupercache_buffer" (in wp-cache-phase2.php) that is used to modify the page before it is cached and the cache action "wpsc_cachedata" (in wp-cache-phase1.php) is used to modify the cached page just before it's served.

Originally published here.