Using RunCache Hooks and Filters for Custom Development

RunCache is built to provide high-speed caching for your WordPress web applications right out of the box. If you are a developer or site builder, you can also customize how RunCache behaves by using custom code.

Since RunCache uses standard WordPress functions like apply_filters() and do_action(), you can interact with them using standard WordPress add_filter() and add_action() functions.

When to Register Your Hooks

All RunCache modules initialize on the standard plugins_loaded WordPress hook.

If your code modifies settings before the plugin reads them, you must register your callbacks before plugins_loaded completes. The most reliable way to do this is inside a Must-Use plugin (located in wp-content > mu-plugins) or at the top of your active theme’s functions.php file.

Important Timing Note for Exclusion Rules

The runcache_rules_settings filter has a unique timing requirement. The early cache drop-in file reads exclusion rules before WordPress fully loads. Because of this, standard callbacks will not intercept the early check. The drop-in file reads a generated configuration file instead. If you need to bypass page caching dynamically in your custom code, follow our guide on how to exclude a page from cache using code.

How to Add a RunCache Hook

To add a custom filter or action to your site, follow these steps:

1. Connect to your server using SFTP, SSH, or the RunCloud File Manager.
2. Navigate to wp-content > mu-plugins. If the mu-plugins directory does not exist, create it.
3. Create a new PHP file, such as runcache-custom.php.
4. Open the file and write your custom hook callback.
5. Save the file and verify your site functionality in your browser.

For example, you can use the following code to email the administrator whenever Redis caching is turned off:

add_action( 'runcache_redis_cache_disabled', function( $provider ) {
    $admin = get_option( 'admin_email' );
    wp_mail( $admin, '[Alert] Redis Disabled', 'Redis cache was turned off. Database load may increase.' );
} );

In the code snippet above, the provider status actions are triggered whenever server-level caching layers are toggled. These are useful for sending instant alerts or audit logs when critical caches such as Redis or NGINX are disabled in production, helping prevent unexpected spikes in database performance.

RunCache Filters

Filters let you intercept and modify data before RunCache stores it, reads it, or sends it to the server.

Settings and Provider Filters

Edge Cache and Purge Filters

Cache Statistics Filters

Standalone Utility Filters

RunCache registers handlers for two filters that you can trigger manually from your own code:

• apply_filters( 'runcache_get_stats', $value ): Retrieves the current cache statistics array.
• apply_filters( 'runcache_purge_and_preload', $value ): Clears the cache completely and immediately triggers a background preload sweep. Note that clicking the Purge cache and Preload cache buttons in the WordPress admin uses an AJAX request rather than this filter.

RunCache Actions

Actions allow your custom code to run tasks when specific cache events happen.

Settings Lifecycle Actions

These actions run whenever an administrator updates configuration tabs in the RunCache dashboard.

Purge and Preload Actions

Use these actions to trigger third-party services, notify uptime monitors, or write log messages when cache flushes occur. Each of these actions also clears the cached dashboard metrics.

Provider Status Actions

These actions run when an administrator toggles a server-level cache provider on or off.

Related Developer Guides

To continue customizing your caching infrastructure, review our related technical guides:

• Learn about the WordPress constants you can set in wp-config.php to control cache paths and debugging.
• Learn how to read the plugin logs to troubleshoot failures in WordPress.