TurboCache: Hooks and filters
Every TurboCache action and filter with its arguments: cache bypass, dependency URLs, critical scripts, final HTML, server cache purges and more.
All hooks use the turbocache_ prefix. The older wpca_ names from the plugin’s former name, WPCraft Accelerator, still work as deprecated aliases (with a notice when WP_DEBUG is on). Add them in a small custom plugin or your child theme’s functions.php. The plugin boots on plugins_loaded priority 5, so register your callbacks before that or at the top level of your plugin file.
Filters
Caching decisions
turbocache_cache_skip_reason—( string $reason, TurboCache_Request $request ). Return a non-empty string to stop the current response being cached; it appears inX-TurboCache-Cache: BYPASS; reason=…. Return''to allow caching.turbocache_is_optimizable_request—( bool $ok, TurboCache_Request $request ). Whether the request may go through the optimisation pipeline. Returning false also prevents caching.turbocache_dropin_config—( array $config ). The configuration written toconfig.phpand read by the drop-in before WordPress loads (exclusions, views, encodings, headers).turbocache_default_settings—( array $defaults ). The full default settings tree.
Revalidation
turbocache_post_dependency_urls—( string[] $urls, WP_Post $post, bool $deleted ). URLs refreshed when a post changes.turbocache_site_urls—( string[] $urls ). URLs collected for a whole-site revalidation (home, published posts of public types, archives, terms).turbocache_skip_post_types—( string[] $types ). Post types left out of whole-site revalidation (Divi and Elementor library types, block templates, WooCommerce orders and coupons and others by default).
Optimisation
turbocache_js_critical_patterns—( string[] $patterns, object $ctx ). Patterns for scripts that are never delayed (built-ins plus the Critical scripts setting).turbocache_final_html—( string $html, object $ctx ). The optimised page just before it is stored.turbocache_optimizers—( array $optimizers, TurboCache_Plugin $plugin ). The optimiser objects keyedhtml,content,compat,images,frames,css,js.
Server caches
turbocache_server_caches—( array $layers ). Detected caching layers; each item hasid,labelandpurge(bool).turbocache_server_cache_purge_{id}—( bool $ok, string[]|null $urls ). Called for a layer you added with an unknown id; do the purge and return true on success.$urlsis null for a full purge.turbocache_purge_opcache—( bool $purge = false ). Return true to reset PHP OPcache on full purges.
Actions
turbocache_loaded—( TurboCache_Plugin $plugin ). Plugin fully booted.turbocache_activated/turbocache_deactivated— no arguments.turbocache_settings_saved—( array $settings ). After settings are saved, imported or reset.turbocache_purge_all— no arguments. Fired after a full delete or a site-wide update.turbocache_cache_purged— no arguments. Every cached page entry was deleted.turbocache_cache_invalidated_all—( bool $delete ). Every entry was marked stale (lazy invalidation path).turbocache_cache_url_invalidated—( string $url, bool $delete ). One URL was marked stale or deleted.turbocache_server_cache_purged—( array $result );turbocache_server_cache_purged_urls—( string[] $urls, array $result ).$resulthaspurgedanderrorslabel lists.turbocache_db_cleanup_done—( array $results ). Counts forrevisions,autodrafts,trash,comments,transients,tables.turbocache_process_image—( string $absolute_path ). The plugin listens to this to convert one image and its sizes to WebP/AVIF; you can fire it yourself, e.g. after an import.
Example
// Never cache pages that show a live stock ticker shortcode.
add_filter( 'turbocache_cache_skip_reason', function ( $reason, $request ) {
if ( '' === $reason && is_singular() && has_shortcode( get_post()->post_content, 'stock_ticker' ) ) {
return 'stock-ticker'; // Shows as "X-TurboCache-Cache: BYPASS; reason=stock-ticker".
}
return $reason;
}, 10, 2 );
// When an event post changes, also refresh the events landing page.
add_filter( 'turbocache_post_dependency_urls', function ( $urls, $post, $deleted ) {
if ( 'event' === $post->post_type ) {
$urls[] = home_url( '/whats-on/' );
}
return $urls;
}, 10, 3 );
// Keep a booking widget script out of the delay list everywhere.
add_filter( 'turbocache_js_critical_patterns', function ( $patterns ) {
$patterns[] = 'booking-widget.js';
return $patterns;
} );
Constants
TURBOCACHE_CACHE_DIR— cache root, defaultWP_CONTENT_DIR . '/cache/turbocache/'(WPCA_CACHE_DIRis still read as a fallback). The page-cache drop-in follows a custom folder; the optional object cache always uses the default path.DONOTCACHEPAGE— the standard WordPress constant is respected (reason=donotcachepage).
Did this answer the question? No — open a support request