Skip to content

Developers Start Here

Jump to bottom
thingalon edited this page Feb 1, 2023 · 5 revisions

Ported over from: https://odd.blog/wp-super-cache-developers/

WP Super Cache is a full page caching plugin for WordPress that can dramatically speed up blogs.

The plugin is very flexible and can be configured or modified with the aid of filters, actions and the configuration file to handle many situations.

The plugin operates in two modes. Simple and Expert. In both modes, cached static files for anonymous users are generated in the same way in the supercache cache folder (usually wp-content/cache/supercache/). They differ in how the files are served.

In Simple mode a small part of WordPress is loaded and PHP runs to check the visitor is anonymous (doesn’t have any login/comment/other cookies). It looks for a cached page and serves it to the visitor if found.

In Expert mode mod_rewrite is used to serve cached files. It does the same checks on cookies and if a cached page is available that will be served to the visitor. It’s marginally faster than using PHP to serve cache files but it’s harder to get working. I recommend using Simple mode.

If you have “Cache HTTP headers with page content” enabled, or a visitor is logged in or left a comment their visit will be cached in a non-anonymous cache file. This file will have visitor specific information in it so it will only be served to the same visitor if they return to that page again. This makes caching for these types of users very inefficient and is the reason there’s a “Don’t cache pages for known users” setting.

In this mode, the cache files are created in the same folders as the other cache files using a filename created from an md5 of the current url, gzip encoding status and the user’s cookies. The mobile user agent may also be added if that’s switched on. The filename may finally be filtered using the “wp_cache_key” filter as explained below.

Configuration

The configuration file is WP_CONTENT_DIR/wp-cache-config.php (usually wp-content/wp-cache-config.php). The configuration is stored in a file because the plugin loads before the database library is loaded. You can modify or add to the configuration file using wp_cache_setting() or wp_cache_replace_line(). Using wp_cache_setting() is preferred.

wp_cache_setting( $setting, $value )

Parameters: $setting is the name of the setting to be updated. $value is the value of the setting.

Example:

wp_cache_setting('wp_cache_mobile_enabled', 1 );

wp_cache_replace_line($old, $new, $my_file)

Parameters: $old is a regular expression matching an existing line in the file. $new is the new line to replace or be inserted. $my_file is the actual file. Example:

wp_cache_replace_line('^ *\$wp_cache_mobile_enabled', "\$wp_cache_mobile_enabled = 1;", $wp_cache_config_file);

Plugins

WP Super Cache has it’s own plugins folder. It needs this to make it easier to extend as it loads before regular WordPress plugins. These plugins are loaded before the database library, or almost all the regular WordPress include files are loaded. They won’t have access to WordPress features like $wpdb, add_action() or add_filter() when they load.

The plugin folder normally lives in wp-super-cache/plugins/ but by modifying the $wp_cache_plugins_dir variable in the config file you can put it anywhere. That’s a good idea if you develop your own supercache plugins because WordPress will delete the folder wp-super-cache and everything in it when upgrading the plugin.

From version 1.6.3 of WP Super Cache, you can use two functions to add or remove plugins from loading:

  1. wpsc_add_plugin( $filename );
  2. wpsc_delete_plugin( $filename );

The files you add can live anywhere on your host where PHP can load them.

You can also put plugin files in a wp-super-cache-plugins directory in the same directory where the wp-super-cache directory lives. See #574 for more information.

Plugins can interact with the early initialization process using the “cacheaction” functions. add_cacheaction() and do_cacheaction() work exactly like their WordPress equivalents.

add_cacheaction( $action, $func )

Parameters: $action is the hook to add an action on. $func is the function to run when the specified hook or action is executed.

Example:

add_cacheaction( 'wp_cache_get_cookies_values', 'wp_cache_check_mobile' );

do_cacheaction( $action, $value )

Parameters: $action is the hook to execute. $value is the variable to pass to functions that will execute on this hook.

It will return $value.

Example:

$string = do_cacheaction( 'wp_cache_get_cookies_values', $string );

This will execute any functions added to the ‘wp_cache_get_cookies_values’ hook, and pass $string to each of them.

Two Supercache plugins are included already:

Cacheaction hooks

The following are the cacheaction hooks already defined in WP Super Cache and brief description.

  1. wp_cache_key filters the cache key used to index half-on cache files.
  2. wp_cache_served_cache_file filters the filename of the half-on cache file for the current url.
  3. wp_cache_get_cookies_values filters the cookie string identifying the current visitor.
  4. cache_admin_page allows you to add new content to the WP Super Cache admin page. Use this in your own plugin to add an on/off switch for it on the admin page. See the existing plugins for an example.
  5. add_cacheaction is fired after regular actions are added in wp-cache-phase2.php. Use this cacheaction to execute a function that adds new actions to regular WordPress actions or filters.

Moving things around

You can tell the plugin where various important directories sit:

  1. Define WPCACHEHOME in your wp-config.php to point at where the wp-cache-phase1.php and associated files live. This is usually wp-content/plugins/wp-super-cache/
  2. Point $wp_cache_plugins_dir (in wp-cache-config.php) where you want the WP Super Cache plugins folder to live. See “Plugins” section above.
  3. Set $cache_path (in wp-cache-config.php) to where the cache directory should live.

Late Initialisation

If you’re writing a WordPress plugin that needs to modify the cache key used by WP Super Cache but also needs access to the database use this feature.

Set $wp_super_cache_late_init to 1 in your cache config file.

This will cause the plugin to delay setting the cache key until the “init” hook in WordPress executes. It has a really low priority of 9999 so it’s likely to run after any other hooks. This may cause problems with plugins that use this hook to start an output buffer. Consider yourself warned!

The plugin will also enter half-on mode. Now you can modify the cache key using a hook on wp_cache_key and interrogate the database too.

Garbage Collection

Garbage collection is the process of cleaning up stale or obsolete cache files. The garbage collection(GC) process fires off the wp_cache_gc scheduled event in WordPress. This fires off an action of the same that runs the function wp_cache_gc_cron().

If for some reason, the GC process doesn’t run, you can set $wp_cache_shutdown_gc to 1 in the config file so it will execute at the end of each request instead. (It won’t do an actual cleaning up of cache files on each request.) This will result in a slow down, so it’s better to fix your wp-cron system instead.

Clearing the Cache

You can clear the cache by calling the function wp_cache_clear_cache().

function wp_cache_clear_cache() {
        global $cache_path;
        prune_super_cache( $cache_path . 'supercache/', true );
        prune_super_cache( $cache_path, true );
}

Delete the cache files for a single post by using the wp_cache_post_change( $post_id ) function. It will attempt to delete every half-on cache file for that post, as well as any supercache files. You may need to set the global variable $super_cache_enabled to make this function clean out supercached files. In requests that have GET parameters, supercache is disabled, so only wp-cache cache files are created, and likewise deleted. Use this code to set that variable before your call the post change function:

$GLOBALS["super_cache_enabled"]=1;

Filters

It’s possible to filter a number of useful items during the caching process:

  1. do_createsupercache takes the cookie values as a parameter and decides if supercache files should be created or not. Probably of limited use.
  2. supercache_dir filters the supercache directory. 1 parameter, the supercache directory above the directory “supercache”.
  3. wpsupercache_404 returns false by default but have it return true to cache 404 pages.
  4. wpsupercache_buffer filters the content of the page. If your plugin uses an output buffer you could use this filter instead. (Yes, this could be super useful!)
  5. wp_cache_meta filters the meta array stored alongside half-on cache files.
  6. cached_mobile_browsers filters the list of mobile browsers. Load the settings page to activate.
  7. cached_mobile_prefixes filters the list of mobile browser prefixes. Load the settings page to activate.
  8. cached_mobile_groups filters the list of mobile browser groups. Load the settings page to activate.
  9. wp_super_cache_error_checking will allow you to add extra error checking before the plugin settings page loads. Your filter should print a warning message and return false to stop the settings page loading.

I think the most useful filter there could be wpsupercache_buffer. With it, you can examine and modify the page before it’s served and cached. Any plugin that depends on an output buffer could use this instead (and avoid any potential ob conflicts!) The three mobile filters are only useful if you have mobile support switched on. Please see wp_cache_check_mobile() and wp_cache_mobile_group() in wp-cache-phase1.php for how they work.

Do not cache this page

Define the constant DONOTCACHEPAGE at any time before the current request finishes and the current page won’t be cached.

Modifying Headers (Simple mode)

When serving pages in Simple mode, Super Cache sends a Vary header and a Cache Control header on every page load. I do not recommend changing the Vary header but if you want to and understand the consequences of doing so, define the constant WPSC_VARY_HEADER in wp-config.php to be the value of the new header. For example:

define( 'WPSC_VARY_HEADER', 'Accept-Encoding, Cookie' );

In a similar manner, you can define the constant WPSC_CACHE_CONTROL_HEADER to change the Cache-Control header.

define( 'WPSC_CACHE_CONTROL_HEADER', 'max-age=3, must-revalidate' );

Configuring htaccess (Expert mode)

Note: These options are only available in Super Cache 1.9.3 and later.

In Expert mode, cached pages are served directly by your web-server without running any PHP code. As such, headers like Cache-Control and ExpiresByType are written to an .htaccess file in your cache directory. If you would like to modify these headers, you can do so using two filters; wpsc_htaccess_mod_headers to control the headers set by mod_headers, and wpsc_htaccess_mod_expires to control the settings for mod_expires.

These are advanced settings, and we do not recommend tinkering with them unless you are comfortable with Apache configuration.

Here is an example script which will change your cache header and expiry settings to one hour:

add_filter( 'wpsc_htaccess_mod_headers', function( $headers ) {
    $headers['Cache-Control'] = 'max-age=3600, immutable';
    return $headers;
}, 1 );

add_filter( 'wpsc_htaccess_mod_expires', function( $expiry_rules ) {
    $expiry_rules = array_filter( $expiry_rules, function( $rule ) {
        return strpos( $rule, 'ExpiresByType' ) === false;
    } );

    $expiry_rules[] = 'ExpiresByType text/html "access plus 1 hour"';
    return $expiry_rules;
}, 1 );
Clone this wiki locally