BerqWP Cache API - Developer Reference

This guide covers the hooks, filters, and helper functions you can use to programmatically control BerqWP’s page cache from your WordPress theme or plugin.

How BerqWP Caching Works (Quick Overview)

BerqWP caches fully optimized HTML pages as gzip-compressed files on disk. The optimization itself happens off-server via the Photon Engine — a cloud service that optimizes all the webpages. When a visitor requests a page, BerqWP serves the pre-built .gz file directly, bypassing the database entirely.

Cache invalidation is automatic — BerqWP hooks into save_post, switch_theme, comment approval, and other WordPress events to flush and rebuild affected pages. The hooks below let you extend or override this behavior.

Quick Reference

Hook / Function	Type	Purpose
`berqwp_flush_all_cache`	Action	Flush the entire page cache
`berqwp_flush_page_cache`	Action	Flush a single page’s cache
`berqwp_purge_cdn`	Action	Fires after CDN cache is purged
`berqwp_cache_warmup`	Action	Trigger a full site cache warmup
`berqwp_before_update_optimization_mode`	Action	Fires before the optimization mode changes
`berqwp_stored_page_cache`	Action	Fires after a page’s cache is stored
`berqwp_bypass_cache`	Filter	Skip cache for the current request
`berqwp_can_flush_cache_on_post_update`	Filter	Prevent cache flush when a post is saved
`berqwp_can_flush_home_cache_on_post_update`	Filter	Prevent homepage cache flush on post changes
`berqwp_exclude_slug_match`	Filter	Exclude URLs from cache by substring match
`berqwp_post_types`	Filter	Control which post types are cached
`berqwp_purge_home_post_types`	Filter	Control which post types trigger homepage flush
`berqwp_ignored_urls_params`	Filter	Strip query params from cache keys
`berqwp_page_translation_urls`	Filter	Provide translated URLs for cache flush/warmup
`warmup_cache_by_url()`	Function	Queue a URL for cache optimization
`bwp_is_home_cached()`	Function	Check if the homepage is cached
`bwp_cached_pages_count()`	Function	Get the total number of cached pages
`bwp_get_cache_dir()`	Function	Get the cache directory path

Flushing Cache Programmatically

BerqWP handles cache invalidation automatically when content changes. These actions let you trigger flushes manually when your code makes changes that BerqWP can’t detect on its own.

`berqwp_flush_all_cache`

Deletes all cached HTML files, clears warmup transients, and triggers reverse proxy and Cloudflare purges.

// Flush the entire BerqWP cache
do_action( 'berqwp_flush_all_cache' );

When to use: After a bulk content import, after deploying a theme update that changes site-wide markup, or after modifying shared template partials.

Warning: This is expensive on large sites because every page must be re-optimized by the Photon Engine. Prefer per-page flush when possible.

`berqwp_flush_page_cache`

Flushes the cache for a single page. Also purges the reverse proxy and Cloudflare edge cache for that URL.

Parameter: $slug (string) — the URL path, e.g. /about-us/

// Flush cache for a specific page
do_action( 'berqwp_flush_page_cache', '/about-us/' );

// Flush cache for a WooCommerce product
$product_url = get_permalink( $product_id );
$slug = wp_parse_url( $product_url, PHP_URL_PATH );
do_action( 'berqwp_flush_page_cache', $slug );

When to use: After updating content through a custom form, external API sync, or any code path that doesn’t trigger WordPress’s save_post hook.

`berqwp_purge_cdn`

Fires after BerqWP purges its own CDN. Hook into this to purge your own CDN or external cache layer at the same time.

add_action( 'berqwp_purge_cdn', function () {
    // Purge your own CDN
    my_cdn_purge_all();
});

`berqwp_cache_warmup`

Triggers a full site cache warmup — BerqWP crawls the sitemap and queues all URLs for optimization.

// Trigger a full cache warmup
do_action( 'berqwp_cache_warmup' );

Note: Warmup runs asynchronously. This action queues the process — it does not block until all pages are cached.

`berqwp_before_update_optimization_mode`

Fires before the optimization mode (Basic, Medium, Blaze, Aggressive) changes. BerqWP uses this internally to delete all cache files, since a mode change produces different HTML output.

add_action( 'berqwp_before_update_optimization_mode', function () {
    // Run custom cleanup before mode switch
    my_plugin_clear_inline_styles();
});

Hooking Into Cache Storage

`berqwp_stored_page_cache`

Fires after a page’s optimized HTML has been stored to disk. Use this to trigger downstream actions like logging, notifications, or syncing to an external system.

Parameter: $slug (string) — the page slug that was just cached

add_action( 'berqwp_stored_page_cache', function ( $slug ) {
    error_log( "BerqWP cached page: $slug" );
});

Controlling Cache Behavior

`berqwp_bypass_cache`

Return true to completely skip caching for the current request. This prevents both serving from cache and generating a new cache file.

Default: false

// Bypass cache for requests with a specific cookie
add_filter( 'berqwp_bypass_cache', function ( $bypass ) {
    if ( isset( $_COOKIE['my_app_session'] ) ) {
        return true;
    }
    return $bypass;
});

// Bypass cache for a specific URL path
add_filter( 'berqwp_bypass_cache', function ( $bypass ) {
    if ( strpos( $_SERVER['REQUEST_URI'], '/members/' ) !== false ) {
        return true;
    }
    return $bypass;
});

Performance note: This filter runs on every frontend request. Keep your callback fast — avoid database queries or remote API calls here.

BerqWP uses this internally for: parameter, preload requests, crawler detection, and sandbox mode.

`berqwp_can_flush_cache_on_post_update`

Return false to prevent BerqWP from flushing a page’s cache when save_post fires. Useful during bulk operations where you want to flush once at the end instead of on every post save.

Default: true

// Prevent per-post cache flush during a bulk import
global $my_bulk_import_running;
$my_bulk_import_running = false;

add_filter( 'berqwp_can_flush_cache_on_post_update', function ( $can_flush ) {
    global $my_bulk_import_running;
    if ( $my_bulk_import_running ) {
        return false;
    }
    return $can_flush;
});

// In your import code:
$my_bulk_import_running = true;
foreach ( $posts as $post_data ) {
    wp_insert_post( $post_data );
}
$my_bulk_import_running = false;

// Flush everything once at the end
do_action( 'berqwp_flush_all_cache' );

`berqwp_can_flush_home_cache_on_post_update`

Return false to prevent the homepage cache from being flushed when a post’s status changes. By default, BerqWP flushes the homepage when any post type is published, unpublished, or updated.

Default: true

// Don't flush homepage cache when posts are updated
add_filter( 'berqwp_can_flush_home_cache_on_post_update', '__return_false' );

Cache Exclusions

`berqwp_exclude_slug_match`

Add URL substrings that should never be cached. BerqWP checks each URL against this list using strpos() — if any item is found in the URL, the page is excluded from caching.

Parameter: $exclude_items (array) — list of URL substrings Return: Modified array

add_filter( 'berqwp_exclude_slug_match', function ( $exclude_items ) {
    // Exclude all URLs containing /members/ or /api/
    $exclude_items[] = '/members/';
    $exclude_items[] = '/api/';
    return $exclude_items;
});

BerqWP already excludes: WooCommerce checkout/cart endpoints, pagination (/page/), search (/search/), embeds, and URLs with query parameters. You don’t need to add these manually.

`berqwp_post_types`

Control which post types BerqWP includes for cache optimization. This filter runs during plugin setup and the result is saved to the berqwp_post_type_names option.

Parameter: $post_type_names (array) — all public post types minus attachment Return: Modified array

// Remove a custom post type from caching
add_filter( 'berqwp_post_types', function ( $post_types ) {
    return array_diff( $post_types, [ 'internal_doc' ] );
});

// Add a normally non-public post type to caching
add_filter( 'berqwp_post_types', function ( $post_types ) {
    $post_types[] = 'landing_page';
    return $post_types;
});

`berqwp_purge_home_post_types`

Control which post types trigger a homepage cache flush when their status changes (e.g. published, unpublished, updated).

Default: ['post']

// Also flush homepage when WooCommerce products change
add_filter( 'berqwp_purge_home_post_types', function ( $post_types ) {
    $post_types[] = 'product';
    return $post_types;
});

`berqwp_ignored_urls_params`

Add query parameters that BerqWP should strip before computing cache keys. This prevents duplicate cache entries for the same page with different tracking parameters.

Parameter: $tracking_params (array) — list of query parameter names Return: Modified array

add_filter( 'berqwp_ignored_urls_params', function ( $params ) {
    // Ignore custom tracking parameters
    $params[] = 'my_ref';
    $params[] = 'campaign_id';
    return $params;
});

BerqWP already ignores: Common tracking parameters like utm_source, utm_medium, utm_campaign, fbclid, gclid, and many more.

Multilingual Cache Support

`berqwp_page_translation_urls`

When BerqWP flushes or warms up cache for a page, this filter lets you provide translated versions of that URL so all language variants are handled together.

Parameters: $urls (array, default []), $page_url (string — the original URL being flushed/warmed) Return: Array of translated URLs

// WPML integration
add_filter( 'berqwp_page_translation_urls', function ( $urls, $page_url ) {
    $post_id = url_to_postid( $page_url );
    if ( ! $post_id ) {
        return $urls;
    }

    $languages = apply_filters( 'wpml_active_languages', [] );
    foreach ( $languages as $lang ) {
        $translated_id = apply_filters( 'wpml_object_id', $post_id, get_post_type( $post_id ), false, $lang['code'] );
        if ( $translated_id && $translated_id !== $post_id ) {
            $urls[] = get_permalink( $translated_id );
        }
    }

    return $urls;
}, 10, 2 );

Helper Functions

`warmup_cache_by_url()`

Queue a URL for cache optimization via the Photon Engine.

warmup_cache_by_url( string $page_url, bool $is_forced = false, bool $async = false )

Parameter	Type	Description
`$page_url`	string	Full URL to cache (e.g. `https://example.com/about/`)
`$is_forced`	bool	If `true`, sets queue priority to 1 (highest). Default: `false` (priority 5)
`$async`	bool	If `true`, uses a 1-second HTTP timeout (fire-and-forget). Default: `false` (30s timeout)

// Force-warmup a page after a custom content update
$page_url = get_permalink( $post_id );
warmup_cache_by_url( $page_url, true );

Limitations:

Skips URLs with query parameters
Skips file URLs (e.g. .php, .xml)
Skips excluded and non-optimizable URLs
Does not work on localhost

`bwp_is_home_cached()`

Check whether the homepage has a cached file.

Returns: bool

if ( bwp_is_home_cached() ) {
    // Homepage cache exists
}

`bwp_cached_pages_count()`

Get the total number of cached pages (counts .gz files in the cache directory).

Returns: int

$count = bwp_cached_pages_count();
echo "BerqWP has $count pages cached.";

`bwp_get_cache_dir()`

Get the absolute path to BerqWP’s cache directory. Multisite-aware — appends site-{id}/ on multisite installations.

Returns: string

$cache_dir = bwp_get_cache_dir();
// Single site: /path/to/wp-content/cache/berqwp/html/
// Multisite:   /path/to/wp-content/cache/berqwp/html/site-2/

Cache File Storage

For developers who need to interact with cache files directly (e.g. building monitoring tools or custom purge logic):

Detail	Value
Base directory	`WP_CONTENT_DIR . '/cache/berqwp/html/'`
Multisite directory	`WP_CONTENT_DIR . '/cache/berqwp/html/site-{blog_id}/'`
File naming	`md5( $page_url ) . '.gz'`
Compression	gzip, level 9
Cache lifespan	Configurable in BerqWP settings (default: 30 days)
Cache key	MD5 hash of the full page URL (lowercased, ignored params stripped)

Pages that are never cached:

Logged-in users
Non-GET requests
Admin pages, previews, 404s, search results
Cron, AJAX, and REST API requests
WP-CLI requests
Pages excluded via settings or filters

Common Recipes

Flush all cache after a bulk import

Disable per-post flush during the import, then flush everything once at the end:

add_filter( 'berqwp_can_flush_cache_on_post_update', '__return_false' );
add_filter( 'berqwp_can_flush_home_cache_on_post_update', '__return_false' );

// ... run your import ...

remove_filter( 'berqwp_can_flush_cache_on_post_update', '__return_false' );
remove_filter( 'berqwp_can_flush_home_cache_on_post_update', '__return_false' );

do_action( 'berqwp_flush_all_cache' );

Exclude a custom post type from caching

add_filter( 'berqwp_post_types', function ( $post_types ) {
    return array_diff( $post_types, [ 'my_custom_type' ] );
});

Bypass cache for WooCommerce cart and checkout

BerqWP already handles this through cookie detection in most cases. If you need explicit control:

add_filter( 'berqwp_bypass_cache', function ( $bypass ) {
    if ( function_exists( 'is_cart' ) && ( is_cart() || is_checkout() ) ) {
        return true;
    }
    return $bypass;
});

Integrate with WPML for multilingual cache

add_filter( 'berqwp_page_translation_urls', function ( $urls, $page_url ) {
    $post_id = url_to_postid( $page_url );
    if ( ! $post_id ) {
        return $urls;
    }

    $languages = apply_filters( 'wpml_active_languages', [] );
    foreach ( $languages as $lang ) {
        $translated_id = apply_filters( 'wpml_object_id', $post_id, get_post_type( $post_id ), false, $lang['code'] );
        if ( $translated_id && $translated_id !== $post_id ) {
            $urls[] = get_permalink( $translated_id );
        }
    }
    return $urls;
}, 10, 2 );

Warm up a single page after a custom content update

// After your custom update logic
$page_url = get_permalink( $post_id );

// Flush old cache first
$slug = wp_parse_url( $page_url, PHP_URL_PATH );
do_action( 'berqwp_flush_page_cache', $slug );

// Queue for re-optimization with high priority
warmup_cache_by_url( $page_url, true );

How BerqWP Caching Works (Quick Overview)

Quick Reference

Flushing Cache Programmatically

berqwp_flush_all_cache

berqwp_flush_page_cache

berqwp_purge_cdn

berqwp_cache_warmup

berqwp_before_update_optimization_mode

Hooking Into Cache Storage

berqwp_stored_page_cache

Controlling Cache Behavior

berqwp_bypass_cache

berqwp_can_flush_cache_on_post_update

berqwp_can_flush_home_cache_on_post_update