Integrate progressive JSON reads

pom_cache_json_read() retrieves one validated current-site JSON artifact during the WordPress phase. It returns the stored JSON string on success and null when the runtime, path, file, size, payload, or read policy rejects it.

Read a known path

$relative_path = 'archive/book/page-2.json';
$context = array(
    'integration' => 'my_catalog',
    'post_type'   => 'book',
);

$json = function_exists( 'pom_cache_json_read' )
    ? pom_cache_json_read( $relative_path, $context )
    : null;

if ( null !== $json ) {
    $payload = json_decode( $json, true );
}

The helper requires:

• the progressive JSON master switch;
• the WordPress read-fallback switch;
• a safe relative path ending in .json;
• an existing readable non-empty file;
• a file no larger than the configured maximum;
• valid JSON;
• an allowed pom_cache_json_can_serve_cached_file decision.

It does not generate a missing payload.

Veto a read

add_filter(
    'pom_cache_json_can_serve_cached_file',
    static function ( $can_serve, $file, $context ) {
        unset( $file );

        if ( ! $can_serve ) {
            return false;
        }

        if ( ! empty( $context['force_dynamic'] ) ) {
            return false;
        }

        return true;
    },
    10,
    3
);

Preserve a prior rejection. Context differs by caller:

• a WordPress helper call receives the context supplied by that integration;
• an early URL hit includes phase, relative_path, and request_uri.

Do not assume that every key exists. A conventional plugin's callback may also load too late to affect a completed drop-in or Apache hit.

POM Theme fallback integration

POM Cache listens to:

apply_filters(
    'pom_progressive_archive_cached_json',
    $cached_json,
    $relative_path,
    $context
);

It attempts a read only when another provider has not already supplied a value—that is, when $cached_json is strictly null. Third-party providers should preserve a non-null result:

add_filter(
    'pom_progressive_archive_cached_json',
    static function ( $cached_json, $relative_path, $context ) {
        if ( null !== $cached_json ) {
            return $cached_json;
        }

        // Return null to let the next provider or generator continue.
        return null;
    },
    5,
    3
);

Return and error handling

Treat null as a cache miss and proceed to your canonical generator. Do not display an error merely because no cache file exists. A cache is an optimization, not the source of record.

Do not decode and re-encode a cached string unless your integration needs a data structure; POM Cache already validates that the stored bytes are JSON.

When a read is unexpectedly missing, inspect the JSON master, WordPress fallback, relative path, maximum size, file count, and generation/write path in that order.