Integrate progressive JSON purging

POM Cache supports exact-file deletion, current-site deletion, post-triggered deletion, and limited archive-context deletion. Select the helper only after understanding its fallback scope.

Delete one exact file

$relative_path = 'archive/book/page-2.json';

if (
    function_exists( 'pom_cache_json_normalize_relative_path' )
    && function_exists( 'pom_cache_json_delete' )
    && '' !== pom_cache_json_normalize_relative_path( $relative_path )
) {
    pom_cache_json_delete(
        $relative_path,
        array( 'context' => 'my_plugin_page_refresh' )
    );
}

pom_cache_json_delete() returns true only if an existing file is removed.

Use pom_cache_json_purge() carefully

With a valid relative_path, pom_cache_json_purge() deletes that exact file and emits purge actions:

$normalized = pom_cache_json_normalize_relative_path( $relative_path );
if ( '' === $normalized ) {
    return;
}

pom_cache_json_purge(
    array(
        'relative_path' => $normalized,
        'context'       => 'my_plugin_page_refresh',
    )
);

If relative_path is missing or invalid, the helper performs a full current-site JSON purge. Never pass unchecked request input and assume an invalid path will become a no-op.

Purge an archive context

pom_cache_json_purge_context(
    array(
        'post_type' => 'book',
        'locale'    => 'es_ES',
        'context'   => 'my_plugin_book_archive',
    )
);

With a valid post_type, this removes the current site's archive subtree for that post type. When the POM Theme progressive context class is available, locale can add its locale URL prefix.

Without a post_type, pom_cache_json_purge_context() falls back to a full current-site JSON purge. Sanitize and require the post type before calling when targeted scope is mandatory.

Tag helper scope

pom_cache_json_purge_tags( $tags ) currently ignores the tag list and performs a full current-site JSON purge. It exists as a compatibility contract, not as a tag index.

Do not call it inside a loop or describe it as targeted deletion.

Observe a purge

add_action(
    'pom_cache_json_before_purge',
    static function ( $args ) {
        // Record only non-sensitive context if needed.
    }
);

add_action(
    'pom_cache_json_after_purge',
    static function ( $args, $deleted ) {
        // $deleted is the number of files removed for this operation.
    },
    10,
    2
);

Exact-path and full pom_cache_json_purge() operations emit both actions. Do not assume every lower-level deletion or context-subtree helper emits them.

Site and post helpers

pom_cache_json_delete_site_cache( $context ) applies the shared and JSON-specific site-deletion filters, then removes the current site's JSON tree.

pom_cache_json_delete_site_cache_for_post( $post_id, $post, $context ) skips revisions, autosaves, invalid or non-viewable posts, applies pom_cache_json_clear_post_cache, and then performs the site-level purge. It returns the post ID.

Settings-triggered JSON purge

pom_cache_json_purge_on_settings_changes defaults to false. Enabling it registers integrations for POM Framework and faceted-search settings:

add_filter( 'pom_cache_json_purge_on_settings_changes', '__return_true' );

The default watched POM Framework pages are pom-theme-options and pom-translate. Extend them without removing existing entries:

add_filter(
    'pom_cache_json_framework_settings_purge_pages',
    static function ( $pages, $page_slug, $tab, $subsection ) {
        unset( $page_slug, $tab, $subsection );
        $pages[] = 'my-plugin-settings';

        return array_values( array_unique( $pages ) );
    },
    10,
    4
);

This global setting integration is appropriate only when a save on the watched page can change progressive JSON.