Code Snippets#

Ready-to-use code for common Docket Cache tasks.

This page collects small pieces of code that we often share on the support forum. Copy the one you need.

There are two places to put the code:

• wp-config.php for lines that start with define(. Put them above the line /* That's all, stop editing! Happy publishing. */.
• wp-content/mu-plugins/ for the PHP files. Create the mu-plugins folder if it does not exist. Files in this folder load by themselves and are not changed when Docket Cache is updated.

Clear the cache#

From your own code#

Use the standard WordPress function. It is safe to call with or without Docket Cache.

wp_cache_flush();

From the command line#

wp cache flush

See WP-CLI for the other commands.

When a post is saved#

WordPress updates the cache by itself when you edit a post. Use this only if your site still shows old content after saving.

Save as wp-content/mu-plugins/docketcache_flush_when_save_post.php:

<?php
add_action('docketcache/init', function($docket_cache) {
    add_action('save_post', function($post_id, $post, $update) use($docket_cache) {
        $result = $docket_cache->flush_cache(true);
        $docket_cache->co()->lookup_set('occacheflushed', $result);
        do_action('docketcache/action/flush/objectcache', $result);
    }, 10, 3);
});

When a plugin or theme is updated#

Useful when a remote management tool, such as InfiniteWP, shows a wrong update count.

Save as wp-content/mu-plugins/docketcache_flush_when_plugin_update.php:

<?php
add_action('docketcache/init', function($docket_cache) {
    add_action('upgrader_process_complete', function($wp_upgrader, $options) use($docket_cache) {
        if ('update' !== $options['action']) {
            return;
        }

        $result = $docket_cache->flush_cache(true);
        $docket_cache->co()->lookup_set('occacheflushed', $result);
        do_action('docketcache/action/flush/objectcache', $result);
    }, 10, 2);
}, PHP_INT_MAX);

Every hour or every day#

Useful for widgets such as "most popular posts" that must be refreshed on a schedule.

Save as wp-content/mu-plugins/docketcache_flush_every_hour.php:

<?php
add_action('docketcache/init', function($docket_cache) {
    add_action('docketcache_flush_every_hour', function() use($docket_cache) {
        $result = $docket_cache->flush_cache(true);
        $docket_cache->co()->lookup_set('occacheflushed', $result);
        do_action('docketcache/action/flush/objectcache', $result);
    });

    if (!wp_next_scheduled('docketcache_flush_every_hour')) {
        wp_schedule_event(time(), 'hourly', 'docketcache_flush_every_hour');
    }
});

To run it once a day, change 'hourly' to 'daily'.

Only one part of the cache#

Docket Cache keeps some data in its own cache groups. You can clear one group and leave the rest.

// Menu cache
wp_cache_flush_group('docketcache-menu');

// Translation cache
wp_cache_flush_group('docketcache-mo');

// Precache
wp_cache_flush_group('docketcache-precache');

// Transients
wp_cache_flush_group(['transient', 'site-transient']);

Skip caching for some data#

Docket Cache cannot skip a page, but it can skip a cache group or a cache key. Turn on Cache Log on the Configuration screen to find the group and key. See the FAQ for the steps.

Skip a whole group#

define('DOCKET_CACHE_IGNORED_GROUPS', [
    'counts',
    'plugins',
    'themes',
]);

Setting this constant replaces the default list, so keep counts, plugins and themes and add your own groups after them. See DOCKET_CACHE_IGNORED_GROUPS.

Skip one key in a group#

This example stops the WordPress cron list from being cached:

define('DOCKET_CACHE_IGNORED_GROUPKEY', [
    'options' => ['cron'],
]);

This example helps when a remote management tool shows a wrong list of plugins or updates:

define('DOCKET_CACHE_IGNORED_GROUPKEY', [
    'options' => ['active_plugins', 'uninstall_plugins', 'alloptions'],
    'site-transient' => ['update_plugins'],
]);

See DOCKET_CACHE_IGNORED_GROUPKEY.

Skip requests with certain URL parameters#

This example turns off the object cache for pages opened by the WooCommerce Products Filter (WOOF) plugin:

define('DOCKET_CACHE_IGNORE_REQUEST', ['swoof', 'woof_text', 'woof_sku', 'woof_author']);

See DOCKET_CACHE_IGNORE_REQUEST.

Keep transients in the database#

Use this when another plugin breaks with an unserialize() error, or stores very large transients.

define('DOCKET_CACHE_TRANSIENTDB', true);

See DOCKET_CACHE_TRANSIENTDB.

Limit the cache size#

Small OPcache on shared hosting#

Some hosts limit OPcache to 128 MB and 10,000 files. WordPress itself uses about 5,000 of those files, so keep the number of cache files low:

// Keep at most 3,000 cache files
define('DOCKET_CACHE_MAXFILE', 3000);

// Check the limit every time a cache file is written
define('DOCKET_CACHE_MAXFILE_LIVECHECK', true);

// Keep cache for 2 days, not 4
define('DOCKET_CACHE_MAXTTL', 172800);

// Use at most 100 MB of disk space
define('DOCKET_CACHE_MAXSIZE_DISK', 104857600);

// Do not cache an object bigger than 1 MB
define('DOCKET_CACHE_MAXSIZE', 1048576);

Allow more cache files#

define('DOCKET_CACHE_MAXFILE', 100000);

Delete expired cache files straight away#

By default an expired cache file is emptied first and removed later by the Garbage Collector. To delete it at once:

define('DOCKET_CACHE_FLUSH_DELETE', true);

To run the Garbage Collector by hand:

wp cache run:gc

Change where the cache is stored#

Bedrock#

Add to config/application.php. Change the paths to match your server.

Config::define('DOCKET_CACHE_CONTENT_PATH', '/var/www/example.com/web/app/cache/docket-cache-content');
Config::define('DOCKET_CACHE_DATA_PATH', '/var/www/example.com/web/app/cache/docket-cache-data');
Config::define('DOCKET_CACHE_PATH', '/var/www/example.com/web/app/cache/docket-cache');

If the web server and PHP run as different users, also give the group write access:

Config::define('FS_CHMOD_FILE', 0664);
Config::define('FS_CHMOD_DIR', 0775);

Multi-Network#

Each sub-network gets its own folder named network-(n), where (n) is the network ID. To choose the folders yourself, for example to put them on a RAM disk:

// Main network
define('DOCKET_CACHE_PATH', '/var/www/example.com/wp-content/cache/docket-cache/main');

// Sub-network with ID 2. Docket Cache adds "network-2" to this path.
define('DOCKET_CACHE_PATH_NETWORK_2', '/var/www/example.com/wp-content/cache/docket-cache/sub');

The constant name must be in capital letters. See DOCKET_CACHE_PATH_NETWORK_(n).

RAM disk#

cd wp-content/
sudo mount -t tmpfs -o size=500m tmpfs ./cache/docket-cache

This needs root access. See the FAQ for details.

Control Docket Cache from your own code#

This file adds action names that you can call from a cron job or from another plugin, for example with do_action('docket_cache_control_flush_cache').

Save as wp-content/mu-plugins/docketcache_control.php:

<?php
add_action('docketcache/init', function($docket_cache) {
    // Clear the object cache
    add_action('docket_cache_control_flush_cache', function() use($docket_cache) {
        $result = $docket_cache->flush_cache(true);
        $docket_cache->co()->lookup_set('occacheflushed', $result);
        do_action('docketcache/action/flush/objectcache', $result);
    });

    // Turn the object cache on
    add_action('docket_cache_control_enable_dropin', function() use($docket_cache) {
        $result = $docket_cache->cx()->install(true);
        do_action('docketcache/action/enable/objectcache', $result);
    });

    // Turn the object cache off
    add_action('docket_cache_control_disable_dropin', function() use($docket_cache) {
        $result = $docket_cache->cx()->uninstall();
        do_action('docketcache/action/disable/objectcache', $result);
    });
});

Turn Docket Cache off in an emergency#

Use this when the site shows an error and you cannot open the WordPress admin. It turns off the object cache, deactivates the plugin and removes the drop-in file.

Save as wp-content/mu-plugins/0-docket-cache-deactivate.php, load any page once, then delete the file:

<?php
// Turn off wp-content/object-cache.php
if (!defined('DOCKET_CACHE_DISABLED')) {
    define('DOCKET_CACHE_DISABLED', true);
}

// Deactivate Docket Cache
add_action('docketcache/init', function($docket_cache) {
    try {
        (new Nawawi\DocketCache\Event($docket_cache))->unregister();
        if (!function_exists('deactivate_plugins')) {
            require_once ABSPATH.'wp-admin/includes/plugin.php';
        }

        deactivate_plugins('docket-cache/docket-cache.php', true);

        if (file_exists(WP_CONTENT_DIR.'/.object-cache-delay.txt')) {
            unlink(WP_CONTENT_DIR.'/.object-cache-delay.txt');
        }

        if (file_exists(WP_CONTENT_DIR.'/object-cache.php')) {
            unlink(WP_CONTENT_DIR.'/object-cache.php');
        }
    } catch (\Throwable $e) {
    }
}, PHP_INT_MAX);

To turn off only the object cache and keep the plugin active, add this line to wp-config.php:

define('DOCKET_CACHE_DISABLED', true);

Turn off single features#

Redirect to the post when a search has one result#

define('DOCKET_CACHE_TWEAKS_SINGLESEARCHREDIRECT_DISABLED', true);

OPcache invalidation from WP-CLI#

define('DOCKET_CACHE_WPCLI_OPCACHE', false);

Automatic updates of Docket Cache#

Set to true to always update automatically, or false to never do it.

define('DOCKET_CACHE_AUTOUPDATE', false);

Server settings#

502 error on Nginx when clearing a large cache#

Clearing many cache files can take longer than Nginx waits for PHP. Give it more time:

location ~ \.php$ {
    fastcgi_read_timeout 300;
}

Or clear the cache with wp cache flush, which does not go through Nginx.

Keep a file out of OPcache#

OPcache reads a list of files to skip from the file named in opcache.blacklist_filename:

opcache.blacklist_filename=/etc/php.d/opcache*.blacklist

Add one path per line to that file. Do not add the Docket Cache folder, or the cache files will be read from disk every time.

Find the cause of a problem#

Turn on the WordPress debug log#

define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);

Errors are written to wp-content/debug.log.

Watch the cache log#

Turn on Cache Log on the Configuration screen, then follow the log file:

tail -f wp-content/.object-cache.log

Each line shows the time, the result (hit or miss), the cache group and key, and the page address:

[2021-07-28 18:19:34 UTC] hit  : "e6e6f4013d03-4f29ea6d5a6b" "site-transient:update_core" "/"

Safe settings to test with#

If the site misbehaves with Docket Cache on, try these settings first. They turn off the extra features and keep only the basic object cache.

define('DOCKET_CACHE_PRECACHE', false);
define('DOCKET_CACHE_TRANSIENTDB', true);
define('DOCKET_CACHE_CHUNKCACHEDIR', false);
define('DOCKET_CACHE_MAXFILE_LIVECHECK', true);
define('DOCKET_CACHE_EMPTYCACHE_IGNORE', true);
define('DOCKET_CACHE_STALECACHE_IGNORE', true);