Serve JSON cache files directly with Apache

Direct Apache delivery is the fastest POM Cache JSON path at the origin: Apache maps a supported progressive archive URL to an existing file before PHP or WordPress starts.

This guide is for administrators who control the origin .htaccess or virtual-host configuration. Complete the PHP-based JSON setup first so a rule problem has a working fallback.

Prerequisites

You need:

• Apache with mod_rewrite;
• mod_headers if Apache should set the JSON response headers shown in the generated block;
• working pretty permalinks;
• Progressive JSON cache and JSON writes enabled;
• at least one generated JSON file;
• a cache path Apache can read;
• a backup and rollback method for the active server configuration.

POM Cache does not edit .htaccess. It only displays a recommended block.

Copy the generated block

1. Open Settings → POM Cache → Advanced. On multisite, use Network Admin → Settings → POM Cache → Advanced.
2. Find Progressive JSON Apache rules.
3. Copy Recommended progressive JSON .htaccess rules.
4. Review every filesystem path against the real document root and Cache Location.
5. Place the block before the standard WordPress rewrite block.
6. Validate the Apache configuration;
7. Reload gracefully when using a virtual-host file, or save the reviewed .htaccess;
8. Request a known generated JSON URL as a logged-out visitor.

Rules placed after the WordPress front-controller rule may never get a chance to serve the file.

Routes covered by the generated rules

The block recognizes both public route families:

/pom-json/<relative-path>.json
/wp-json/pom/v1/progressive-archive/<relative-path>.json

It also recognizes a single safe prefix before either route, which is used for localized URLs:

/es/pom-json/<relative-path>.json
/es/wp-json/pom/v1/progressive-archive/<relative-path>.json

The prefixed segment becomes part of the stored cache path. The remaining JSON path can contain the nested archive directories created by POM Theme.

Conditions enforced

The recommended rules serve a file only when:

• the request method is GET;
• the query string is empty;
• no recognized WordPress login, password-protection, comment-author, WooCommerce session, or cart cookie is present;
• the corresponding file exists below the JSON cache directory.

If any condition fails, the request continues to WordPress. These checks are important: direct Apache delivery cannot ask WordPress whether the current visitor has a private context.

The generated rules do not serve HEAD directly. A HEAD request can continue to PHP early serving or the theme router.

Response headers

With mod_headers, the generated block adds:

Content-Type: application/json; charset=UTF-8
Cache-Control: <policy displayed by POM Cache>
Vary: Accept-Encoding

The Cache-Control value is copied into the server block at the moment you copy it. Changing JSON Cache-Control header later changes PHP delivery and the newly displayed recommendation, but it does not rewrite an already installed Apache block. Update the active server rule deliberately when the policy changes.

The Apache path does not add the PHP diagnostic X-POM-Cache header. The absence of that header is therefore not a miss by itself.

Adapt non-default storage

The displayed mapping assumes a conventional WordPress document root and the standard JSON subdirectory below:

/wp-content/cache/pom-cache-json/

Review the mapping when:

• Cache Location is outside wp-content/cache;
• WordPress runs below a subdirectory;
• Apache's DOCUMENT_ROOT is not the WordPress public root;
• the origin uses symlinks or a release directory;
• the multisite uses subdirectory paths or domain mapping;
• a reverse proxy changes the host received by Apache.

The file tree uses the site's configured host and, where relevant, site path. %{SERVER_NAME} must resolve to the same namespace POM Cache used when it wrote the file. If it does not, keep PHP delivery until the mapping is corrected.

Do not broaden a rule to an arbitrary filesystem path merely to make a miss disappear. The target must remain restricted to the intended JSON cache tree.

Important master-switch behavior

Apache evaluates its copied rules before PHP reads POM Cache settings. If you later set Progressive JSON cache to Disabled but leave the Apache block active, Apache can continue serving existing files.

For a complete direct-delivery rollback:

1. Disable or remove the Apache JSON block;
2. Clear the progressive JSON cache;
3. Verify the URL now reaches the intended PHP or WordPress path;
4. Then change the plugin runtime switches as required.

The same principle applies when moving Cache Location: update the server mapping as part of the move.

Verify direct delivery

Use a JSON URL that already has a file:

1. Request it once and confirm current content;
2. Inspect the response headers;
3. Confirm Content-Type and Cache-Control match the installed rule;
4. Confirm the PHP X-POM-Cache header is absent;
5. Compare origin timing with PHP early delivery;
6. Request the same URL with a query string and confirm the direct rule does not serve it;
7. Repeat while logged in and with a WooCommerce cart/session, where applicable;
8. Test every locale prefix and a representative multisite subsite.

If possible, consult the origin access log to prove that the cache file target was used. Response time alone is not conclusive when a CDN is in front.

Roll back safely

If JSON URLs return 404, HTML, a download prompt, or the wrong site's data:

1. Restore the previous Apache configuration;
2. Verify the PHP early or WordPress fallback still works;
3. Compare the public URL, host namespace, locale prefix, and physical path;
4. Correct the rule offline;
5. Validate and reintroduce it.

For non-Apache servers, do not paste Apache syntax. Use Use POM Cache on Nginx and other web servers and preserve the same method, query, cookie, file-existence, content-type, and path-containment boundaries.