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.

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.

Since WP Super Cache 1.6.3 you can use the “wpsc_add_plugin” action to activate a plugin. You must pass the full path and filename of the plugin to the action like this:

do_action( 'wpsc_add_plugin', ABSPATH . 'wp-content/plugins/myplugin/wpsc-helper.php' );

In a similar fashion you can use the “wpsc_delete_plugin” action to deactivate a plugin. You only need to add a plugin once but if run multiple times it will only be added once.

WP Super Cache plugins can be put anywhere that the web server can load them. If you’re writing a plugin or theme you can activate the plugin in your distribution directory.

Actions

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.

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.

Cookies

WP Super Cache 1.6.3 added the wpsc_add_cookie action. This allows you to change the key used to identify a cache file.

Cookies are one part of the key that tells WP Super Cache what cache file to serve to a visitor. By adding a cookie to the internal cookie list the plugin will know that visitors will a certain cookie should be served a different cache file.

For example, a translation plugin may use the cookie “language” to identify visitors who opted to view a translated website. If that cookie has the value “ie” it will show an Irish translation, “fr” will serve a French translation and so on. If WP Super Cache knows about the “language” cookie it can cache each translated page correctly and then serve it to the appropriate visitor.

The plugin will use the name of the cookie and the value of the cookie to determine the cache file to be used.

Example:

do_action( 'wpsc_add_cookie', 'language' );

You can remove a cookie by using the “wpsc_delete_cookie” action with the same parameter.

Please note that cache files are not refreshed when cookies are added or deleted. You can use the function “wp_cache_clear_cache()” to clear the cache for a given blog. If on a multisite install pass the blog_id of the blog otherwise the contents of the cache directory will be deleted.