Hooks & Filters Reference

This reference is for developers who want to extend or integrate with Warp Performance from their theme’s functions.php, a custom plugin, or a must-use plugin.

All hook names are prefixed with WARP_PERFORMANCE_ unless otherwise noted.

---

Constants

Define these constants before Warp loads (e.g., in wp-config.php or a must-use plugin) to control plugin behavior at the lowest level.

WARP_BYPASS_CACHE

Prevents the current request from being cached or served from cache. The page will always be generated fresh by WordPress.

// In wp-config.php or a must-use plugin
define( 'WARP_BYPASS_CACHE', true );

Use case: Useful inside maintenance scripts, import tools, or any context where you’re generating pages programmatically and don’t want cache interference.

---

Bypassing the Cache

WARP_PERFORMANCE_is_cacheable (filter)

The final gate before a page is written to cache. Return false to prevent the current page from being cached.

Parameters:
$is_cacheable (bool) — Whether the current page should be cached. Default: true.

add_filter( 'WARP_PERFORMANCE_is_cacheable', function( $is_cacheable ) {
    // Don't cache search result pages
    if ( is_search() ) {
        return false;
    }

    // Don't cache pages for a specific custom post type
    if ( is_singular( 'live_event' ) ) {
        return false;
    }

    return $is_cacheable;
} );

Note: This filter runs inside the WordPress context (after template_redirect), so all conditional tags like is_search(), is_singular(), is_user_logged_in() etc. are available.

WARP_PERFORMANCE_request_uri (filter)

Modifies the request URI that Warp uses to look up and store cache files. You can normalize or rewrite it before any cache decision is made.

Parameters:
$request_uri (string) — The raw $_SERVER['REQUEST_URI'].

add_filter( 'WARP_PERFORMANCE_request_uri', function( $uri ) {
    // Strip a custom tracking parameter from the cache key
    $uri = preg_replace( '/[?&]ref=[^&]+/', '', $uri );
    return $uri;
} );

---

Cache Exceptions — Bypasses & Cookies

WARP_PERFORMANCE_cache_file_path (filter)

Filters the resolved cache file path after the URI has been parsed. Returning an empty string or false will prevent caching for that request.

Parameters:
$path (string) — The cache directory path derived from the URL.

add_filter( 'WARP_PERFORMANCE_cache_file_path', function( $path ) {
    // Prevent caching for a specific path prefix
    if ( strpos( $path, '/members/' ) === 0 ) {
        return '';
    }
    return $path;
} );

---

Cache Keys — Query Strings

WARP_PERFORMANCE_cache_include_queries (filter)

Adds query string parameter names to the include list. Parameters in this list are kept as part of the cache key, so ?lang=fr and ?lang=en are cached as separate pages.

By default, Warp includes: lang, currency, orderby, max_price, min_price, rating_filter, page.

Parameters:
$queries (array) — Array of query parameter names to keep in the cache key.

add_filter( 'WARP_PERFORMANCE_cache_include_queries', function( $queries ) {
    // Cache separately by membership tier
    $queries[] = 'tier';
    // Cache separately by view mode
    $queries[] = 'view';
    return $queries;
} );

WARP_PERFORMANCE_cache_file_name (filter)

Full control over the cache file name (hash) for the current request. The name is derived from the logged-in state, user role, currency, and included query parameters.

Parameters:
$file_name (string) — The computed cache file name/hash.

add_filter( 'WARP_PERFORMANCE_cache_file_name', function( $file_name ) {
    // Add A/B test bucket to cache key
    $bucket = $_COOKIE['ab_bucket'] ?? 'default';
    return $file_name . '-' . sanitize_key( $bucket );
} );

---

Logged-in User Caching

WARP_PERFORMANCE_cache_admins (filter)

Controls whether users with administrator capability are served cached pages. Defaults to false (admins always get live pages).

Parameters:
$cache_admins (bool) — Whether to cache pages for admins. Default: false.

add_filter( 'WARP_PERFORMANCE_cache_admins', '__return_true' );

WARP_PERFORMANCE_cache_excluded_roles (filter)

Exclude specific user roles from receiving cached pages. Users with these roles will always get a fresh, uncached page.

Parameters:
$roles (array) — Array of role slugs to exclude. Default: [].

add_filter( 'WARP_PERFORMANCE_cache_excluded_roles', function( $roles ) {
    // Never serve cached pages to premium members
    $roles[] = 'premium_member';
    return $roles;
} );

WARP_PERFORMANCE_role_priority (filter)

When logged-in caching is enabled and a user has multiple roles, this sets the priority order for picking which role defines the cache bucket.

Parameters:
$roles (array) — Ordered array of role slugs, highest priority first. Default: ['shop_manager', 'customer', 'subscriber'].

add_filter( 'WARP_PERFORMANCE_role_priority', function( $roles ) {
    // Put your custom role first in priority
    array_unshift( $roles, 'premium_member' );
    return $roles;
} );

WARP_PERFORMANCE_cache_mobile (filter)

Programmatically control whether the current request is treated as a mobile request for cache-key purposes.

Parameters:
$is_mobile (bool) — Whether to use the mobile cache variant. Default: detected from config.

add_filter( 'WARP_PERFORMANCE_cache_mobile', function( $is_mobile ) {
    // Use a custom mobile detection library
    return My_Mobile_Detect::is_mobile();
} );

---

Auto-purge Control

WARP_PERFORMANCE_auto_purge_urls (filter)

When a post is published or updated, Warp automatically purges a set of URLs (the post URL, homepage, category archives, etc.). Use this filter to add or remove URLs from that list.

Parameters:
$urls (array) — List of URLs that will be purged.
$post_id (int) — The ID of the post that triggered the purge.

add_filter( 'WARP_PERFORMANCE_auto_purge_urls', function( $urls, $post_id ) {
    // Also purge a custom aggregator page when any post updates
    $urls[] = home_url( '/latest-news/' );

    // Purge all URLs for a related taxonomy term
    $terms = get_the_terms( $post_id, 'topic' );
    if ( $terms && ! is_wp_error( $terms ) ) {
        foreach ( $terms as $term ) {
            $urls[] = get_term_link( $term );
        }
    }

    return $urls;
}, 10, 2 );

---

Purge Action Hooks

These actions fire during the cache purge lifecycle. Hook into them to trigger your own cache clearing logic (e.g., clearing a Varnish layer, a custom CDN, or an in-memory store).

WARP_PERFORMANCE_purge_url:before / WARP_PERFORMANCE_purge_url:after

Fires before/after a single URL’s cache is deleted.

Parameters:
$url (string) — The URL being purged.

add_action( 'WARP_PERFORMANCE_purge_url:after', function( $url ) {
    my_cdn_purge_url( $url );
} );

WARP_PERFORMANCE_purge_urls:before / WARP_PERFORMANCE_purge_urls:after

Fires before/after a batch of URLs is purged (e.g., on post save).

Parameters:
$urls (array) — The list of URLs being purged.

add_action( 'WARP_PERFORMANCE_purge_urls:after', function( $urls ) {
    foreach ( $urls as $url ) {
        my_cdn_purge_url( $url );
    }
} );

WARP_PERFORMANCE_purge_pages:before / WARP_PERFORMANCE_purge_pages:after

Fires before/after all cached pages are deleted.

add_action( 'WARP_PERFORMANCE_purge_pages:after', function() {
    // Log the purge event
    error_log( '[MyPlugin] Warp full purge triggered at ' . current_time( 'mysql' ) );

    // Clear your own cache layer
    my_redis_flush_pages();
} );

WARP_PERFORMANCE_purge_everything:before / WARP_PERFORMANCE_purge_everything:after

Fires before/after a complete cache reset (pages + object cache + OPcache).

add_action( 'WARP_PERFORMANCE_purge_everything:after', function() {
    // Notify an external service
    wp_remote_post( 'https://my-service.com/cache-cleared', [
        'body' => [ 'site' => home_url() ],
    ] );
} );

---

HTML Output Filtering

WARP_PERFORMANCE_optimization:after (filter)

Filters the complete HTML string after all Warp optimizations have been applied but before the page is written to cache and sent to the browser. This is the best place to make final HTML modifications.

Parameters:
$html (string) — The fully optimized HTML.

add_filter( 'WARP_PERFORMANCE_optimization:after', function( $html ) {
    // Inject a custom comment
    $html = str_replace( '</body>', '<!-- My Plugin Active --></body>', $html );
    return $html;
} );

WARP_PERFORMANCE_footprint (filter)

Modifies the HTML comment Warp appends at the bottom of cached pages.

Parameters:
$comment (string) — The HTML comment string. Default: <!-- Powered by Warp Performance -->.

// Remove the footer comment entirely
add_filter( 'WARP_PERFORMANCE_footprint', '__return_empty_string' );

// Or customize it
add_filter( 'WARP_PERFORMANCE_footprint', function( $comment ) {
    return '<!-- Cached & optimized by MyAgency using Warp Performance -->';
} );

---

JavaScript Optimization Exclusions

WARP_PERFORMANCE_exclude_from_minify:js (filter)

Exclude JavaScript files from minification by providing a partial URL, file name, or script handle keyword. Any script whose URL contains a listed string will be skipped.

Parameters:
$excludes (array) — Array of keyword strings. Default: [].

add_filter( 'WARP_PERFORMANCE_exclude_from_minify:js', function( $excludes ) {
    // Exclude a specific library
    $excludes[] = 'my-library.js';
    // Exclude all scripts from a specific plugin
    $excludes[] = 'my-plugin/assets/';
    return $excludes;
} );

WARP_PERFORMANCE_exclude_from_delay:js (filter)

Exclude JavaScript files from the “Delay JS” feature. Any script whose URL contains a listed string will execute normally instead of being delayed until user interaction.

Parameters:
$excludes (array) — Array of keyword strings. Populated from settings by default.

add_filter( 'WARP_PERFORMANCE_exclude_from_delay:js', function( $excludes ) {
    // Never delay the payment gateway script
    $excludes[] = 'stripe.js';
    $excludes[] = 'paypal';
    // Never delay a critical theme script
    $excludes[] = 'theme-critical.js';
    return $excludes;
} );

WARP_PERFORMANCE_js_delay_timeout (filter)

Sets the timeout (in milliseconds) after which delayed scripts will execute automatically, even if no user interaction has occurred.

Parameters:
$timeout (int) — Milliseconds before auto-execution. Default: 10.

add_filter( 'WARP_PERFORMANCE_js_delay_timeout', function( $timeout ) {
    // Wait up to 5 seconds before forcing delayed scripts to run
    return 5000;
} );

---

CSS Optimization Exclusions

WARP_PERFORMANCE_exclude_from_minify:css (filter)

Exclude CSS files from minification by providing a partial URL, file name, or stylesheet handle keyword.

Parameters:
$excludes (array) — Array of keyword strings. Default: [].

add_filter( 'WARP_PERFORMANCE_exclude_from_minify:css', function( $excludes ) {
    // Exclude a stylesheet that breaks when minified
    $excludes[] = 'my-complex-grid.css';
    $excludes[] = 'legacy-plugin/style.css';
    return $excludes;
} );

---

Admin Access Control

WARP_PERFORMANCE_allowed_roles (filter)

Controls which user roles have access to the Warp Performance dashboard and REST API endpoints.

Parameters:
$roles (array) — Array of role slugs with access. Default: ['administrator', 'editor'].

// Add a custom role
add_filter( 'WARP_PERFORMANCE_allowed_roles', function( $roles ) {
    $roles[] = 'site_manager';
    return $roles;
} );

// Restrict to administrators only
add_filter( 'WARP_PERFORMANCE_allowed_roles', function( $roles ) {
    return [ 'administrator' ];
} );

---

Cloudflare — Query String Ignore List

WARP_PERFORMANCE_ignore_queries (filter)

When Cloudflare integration is active with “Ignore Query String” enabled, this filter controls which query parameters are included in the Cloudflare cache ignore rule.

Parameters:
$queries (array) — Array of query parameter names that Cloudflare should ignore when caching.

add_filter( 'WARP_PERFORMANCE_ignore_queries', function( $queries ) {
    // Add your own tracking parameters to Cloudflare's ignore list
    $queries[] = 'campaign';
    $queries[] = 'affiliate_id';
    return $queries;
} );

---

Media — YouTube Placeholder

WARP_PERFORMANCE_youtube_placeholder_resolution (filter)

Sets the YouTube thumbnail resolution used for the click-to-play placeholder image.

Parameters:
$resolution (string) — YouTube thumbnail quality key. Default: 'hqdefault'.

Available values (lowest to highest quality):

• default — 120×90
• mqdefault — 320×180
• hqdefault — 480×360 (default)
• sddefault — 640×480
• maxresdefault — 1280×720 (not available for all videos)

add_filter( 'WARP_PERFORMANCE_youtube_placeholder_resolution', function( $res ) {
    return 'sddefault';
} );

---

Config Change Events

WARP_PERFORMANCE_update_config:after (action)

Fires whenever the plugin configuration is saved (e.g., when a user toggles a setting in the dashboard).

Parameters:
$new_config (array) — The updated configuration array. Always present.
$old_config (array) — The previous configuration array. Only present when triggered by a user config save. Not passed when the action fires during a plugin version upgrade. Always set a default value of [] in your callback.

add_action( 'WARP_PERFORMANCE_update_config:after', function( $new_config, $old_config = [] ) {
    // Detect when RUCSS is toggled on (only meaningful on user save, not upgrades)
    if ( ! empty( $new_config['css_rucss'] ) && empty( $old_config['css_rucss'] ) ) {
        WarpPerformance\Purge::purge_pages();
    }

    // Log all config changes in development
    if ( defined( 'WP_DEBUG' ) && WP_DEBUG && ! empty( $old_config ) ) {
        $changed = array_diff_assoc( $new_config, $old_config );
        error_log( '[Warp] Config changed: ' . wp_json_encode( $changed ) );
    }
}, 10, 2 );

WARP_PERFORMANCE_upgraded (action)

Fires after the plugin is upgraded to a new version. Passes no parameters — use the WARP_PERFORMANCE_VERSION constant if you need the new version string.

add_action( 'WARP_PERFORMANCE_upgraded', function() {
    // Run your own migration on upgrade
    my_plugin_run_migration( WARP_PERFORMANCE_VERSION );
} );

---

Programmatic Purging (PHP)

You can call Warp’s purge methods directly from PHP without using hooks.

Purge a Single URL

WarpPerformance\Purge::purge_url( home_url( '/products/my-product/' ) );

Purge Multiple URLs

WarpPerformance\Purge::purge_urls( [
    home_url( '/' ),
    home_url( '/shop/' ),
    home_url( '/products/my-product/' ),
] );

Purge All Cached Pages

WarpPerformance\Purge::purge_pages();

Full Cache Reset

Purges pages, OPcache, and object cache, and also triggers Cloudflare/Bunny CDN purge if configured.

WarpPerformance\Purge::purge_everything();

Example: Purge on Custom Plugin Event

add_action( 'my_plugin_product_updated', function( $product_id ) {
    $product_url = get_permalink( $product_id );
    if ( $product_url ) {
        WarpPerformance\Purge::purge_url( $product_url );
    }
} );

Example: Purge on ACF Options Page Save

add_action( 'acf/save_post', function( $post_id ) {
    if ( $post_id === 'options' ) {
        WarpPerformance\Purge::purge_pages();
    }
} );

---

Full Hook Index

Filters

Filter	Description	Default
WARP_PERFORMANCE_is_cacheable	Final cache decision for current page	true
WARP_PERFORMANCE_request_uri	Modify request URI used for cache lookup	$_SERVER['REQUEST_URI']
WARP_PERFORMANCE_cache_file_path	Modify the cache directory path	Parsed from URI
WARP_PERFORMANCE_cache_file_name	Modify the cache file name/hash	Role + query composite
WARP_PERFORMANCE_cache_include_queries	Query params to include in cache key	[lang, currency, …]
WARP_PERFORMANCE_cache_mobile	Treat request as mobile	Config value
WARP_PERFORMANCE_cache_admins	Cache pages for admin users	false
WARP_PERFORMANCE_cache_excluded_roles	Roles excluded from cache	[]
WARP_PERFORMANCE_role_priority	Order of role precedence for cache key	[shop_manager, …]
WARP_PERFORMANCE_auto_purge_urls	URLs purged on post save	Post + archives
WARP_PERFORMANCE_optimization:after	Final HTML after all optimizations	Processed HTML
WARP_PERFORMANCE_footprint	HTML comment appended to cached pages	Warp comment
WARP_PERFORMANCE_exclude_from_minify:js	Scripts excluded from JS minification	[]
WARP_PERFORMANCE_exclude_from_minify:css	Stylesheets excluded from CSS minification	[]
WARP_PERFORMANCE_exclude_from_delay:js	Scripts excluded from JS delay	Config value
WARP_PERFORMANCE_js_delay_timeout	Auto-execute timeout for delayed scripts (ms)	10
WARP_PERFORMANCE_ignore_queries	Query params for Cloudflare ignore rule	Default ignore list
WARP_PERFORMANCE_youtube_placeholder_resolution	YouTube thumbnail resolution	hqdefault
WARP_PERFORMANCE_allowed_roles	Roles with access to the dashboard	[administrator, editor]
WARP_PERFORMANCE_htaccess_rules	Generated .htaccess rules string	Generated rules

Actions

Action	Description	Parameters
WARP_PERFORMANCE_purge_url:before	Before a single URL is purged	$url
WARP_PERFORMANCE_purge_url:after	After a single URL is purged	$url
WARP_PERFORMANCE_purge_urls:before	Before a batch of URLs is purged	$urls
WARP_PERFORMANCE_purge_urls:after	After a batch of URLs is purged	$urls
WARP_PERFORMANCE_purge_pages:before	Before all pages are purged	—
WARP_PERFORMANCE_purge_pages:after	After all pages are purged	—
WARP_PERFORMANCE_purge_everything:before	Before full cache reset	—
WARP_PERFORMANCE_purge_everything:after	After full cache reset	—
WARP_PERFORMANCE_update_config:after	After settings are saved	$new_config, $old_config (optional)
WARP_PERFORMANCE_upgraded	After plugin version upgrade	none

Constants

Constant	Effect
WARP_BYPASS_CACHE	Set to true to bypass caching for all requests
WARP_PERFORMANCE_CACHE_DIR	Path to the cache directory (read-only)
WARP_PERFORMANCE_PLUGIN_URL	URL to the plugin directory (read-only)