Skip to content

Black Friday 50% off your first year on all premium plugins and the Suite.

See the deals

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.

3 min read · Updated 5 November 2026

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 in X-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 to config.php and 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 keyed html, content, compat, images, frames, css, js.

Server caches

  • turbocache_server_caches — ( array $layers ). Detected caching layers; each item has id, label and purge (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. $urls is 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 ). $result has purged and errors label lists.
  • turbocache_db_cleanup_done — ( array $results ). Counts for revisions, 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, default WP_CONTENT_DIR . '/cache/turbocache/' (WPCA_CACHE_DIR is 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