Prime Cache Manual (Free Edition)

Complete documentation for every setting in the Prime Cache WordPress performance plugin.
Version: 1.10.20 | PHP 7.4+ | WordPress 5.8+ (tested up to 7.0)

Quick Start

Follow these steps right after activating Prime Cache to start seeing performance gains immediately.

1. Install and activate the plugin — Search for “Prime Cache” under Plugins > Add New in your WordPress admin and click Activate.
2. Navigate to Prime Cache — A Prime Cache menu item appears in the left admin sidebar.
3. Check the Dashboard — The Dashboard tab shows cache hit rate, storage usage, feature status, and environment information at a glance.
4. Enable Page Cache — Open the Page Cache tab and turn on page caching. This single step typically yields the largest speed improvement.
5. Enable File Optimization — Open the File Optimization tab and enable HTML, CSS, and JavaScript minification.
6. Optimize Media — Open the Media tab and enable lazy loading.
7. Enable Preloading — Open the Preload tab and enable cache preloading so new visitors receive cached pages from the first request.

Dashboard

The Dashboard is the main landing page for the plugin. Navigate to Prime Cache in the WordPress admin menu to reach it. It provides an at-a-glance view of cache hit rate, storage usage, feature status, and server environment.

Overview

The Dashboard is divided into three main sections:

1. KPI Cards: Key metrics — hit rate, cached page count, storage used, and last purge time — displayed as large summary cards.
2. Feature Status: A list of all major features (page cache, file optimization, media, preload, etc.) showing whether each is currently enabled or disabled.
3. Environment Info: PHP version, WordPress version, server software, and dropin status so you can verify your hosting environment meets plugin requirements.

KPI Cards

The KPI cards at the top of the Dashboard display live metrics about your cache performance.

Feature Status Panel

The Feature Status panel lists all major plugin features with a green (enabled) or grey (disabled) indicator for each. This lets you confirm at a glance which optimizations are active.

Dashboard Widget

Prime Cache adds a widget to the WordPress admin home screen (Dashboard) showing cache hit rate and current cache status. You can check your cache health without leaving the WordPress home screen.

Admin Bar Menu

A Prime Cache menu in the WordPress admin bar provides one-click access to more than ten cache actions from any page on your site (both frontend and admin).

Page Cache

Page caching is the core feature of Prime Cache. It serves static HTML files before WordPress even loads, dramatically reducing page load time. Configure it under Prime Cache > Page Cache.

Overview & How It Works

Prime Cache uses the advanced-cache.php dropin mechanism built into WordPress. The dropin fires at the very start of the WordPress bootstrap process — before any database queries, plugins, or theme code run — and checks whether a valid cache file exists for the current request.

Cache flow:

1. WordPress loads wp-content/advanced-cache.php (generated and managed by Prime Cache).
2. The dropin includes dropins/page-cache.php, which reads the configuration file and evaluates whether the request is cacheable.
3. If a valid cache file exists → it is served immediately via readfile() and WordPress stops loading. This is the fastest possible path.
4. If no cache file exists → WordPress boots normally. Output buffering captures the final HTML and writes a cache file on shutdown.

Cache file storage layout:

wp-content/cache/prime-cache/{host}/{path}/
  index.html              # Desktop HTTP
  index-https.html        # Desktop HTTPS
  index-https-mobile.html # Mobile HTTPS
  index-https.html.gz     # Gzip pre-compressed variant
  meta.json               # Saved response headers

Enable & Basic Settings

Enabling page caching causes Prime Cache to automatically generate wp-content/advanced-cache.php and add define('WP_CACHE', true); to wp-config.php.

Setup steps:

1. Open the Prime Cache > Page Cache tab.
2. Toggle Enable Page Cache on.
3. Click Save Changes.
4. Run Purge Cache from the admin bar.
5. Open an incognito browser window and visit any page on your site to confirm it loads from cache.

Cache Lifespan

Controls how long a cache file is considered valid. After the lifespan expires, the next request for that page regenerates the cache file.

Mobile-Separate Cache

When enabled, Prime Cache maintains separate cache files for desktop and mobile visitors. The plugin detects mobile user-agents and stores the mobile response in index-https-mobile.html rather than the default desktop file.

Enable this setting if your site serves a genuinely different HTML structure to mobile users (e.g., a dedicated mobile theme or a theme that outputs different markup for mobile). Responsive-design sites that serve identical HTML to all devices do not need this option.

Gzip Pre-compression

When enabled, Prime Cache writes a pre-compressed .gz version of each cache file alongside the uncompressed version. Apache’s mod_deflate can then serve the pre-compressed file directly, eliminating the per-request compression overhead and reducing server CPU usage.

The compressed file is named index-https.html.gz and is created automatically when a cache file is written. For best results, use this setting together with .htaccess Optimization.

404 Caching

Caches the “Not Found” response for URLs that return a 404 status. This reduces server load caused by spam bots, link-rot crawlers, and other requests for nonexistent URLs.

Default: Disabled

Browser Cache

Sets Cache-Control HTTP headers that instruct browsers to cache static assets locally for a specified duration. Configure per-file-type lifetimes under Prime Cache > Page Cache > Browser Cache.

.htaccess Optimization

Writes optimized Apache rewrite rules to your site’s .htaccess file. With these rules in place, qualifying GET requests are served directly from cache files without invoking PHP at all — the fastest possible delivery path.

Rules written to .htaccess:

• Cache fast-path: Redirects qualifying GET requests directly to the static cache file, bypassing PHP entirely.
• mod_deflate: Enables gzip compression for text-based responses to reduce transfer size.
• mod_expires: Sets browser cache expiry headers for static assets.
• ETag removal: Strips the ETag response header to reduce header overhead and avoid validation round-trips.

Fast-path eligibility conditions:

The PHP-less fast-path applies only when ALL of the following conditions are met. Requests that do not qualify are handled by the PHP dropin (still very fast, just not zero-PHP).

• The request is a GET request
• The URL has no query string (or “cache with query strings” is disabled)
• No Vary Cookies are configured
• The URL path contains only ASCII characters
• The visitor is not logged in (no wordpress_logged_in_* cookie)

Cache Exclusion

Control which requests are excluded from caching based on URL, cookie, user-agent, or referrer. Configure under Prime Cache > Page Cache > Exclusions.

Overview

Not every page on your site should be cached. Personalized pages, shopping cart pages, and pages that must always reflect live data need to bypass the cache. Prime Cache provides four exclusion methods — URL, cookie, user-agent, and referrer — plus automatic WooCommerce exclusions and a per-post metabox toggle.

URL Exclusion

Enter one URL path per line. Any request whose URL contains the specified string will bypass the cache (partial-match). Regex is not supported — enter plain URL paths.

Example entries:

/myaccount/
/cart/
/checkout/
/members/
/dashboard/

Cookie Exclusion

Enter one cookie name per line. If any of the listed cookies are present in a request, that request bypasses the cache. Useful for excluding logged-in users or visitors with an active shopping session.

Example entries:

wordpress_logged_in
wp-postpass_
woocommerce_cart_hash

Matching is partial: entering wordpress_logged_in will also match wordpress_logged_in_abc123.

User-Agent Exclusion

Enter one user-agent string per line. Requests whose User-Agent header contains any listed string are excluded from caching. Useful for targeting specific bots or legacy browsers that should not receive cached responses.

Referrer Exclusion

Enter one referrer URL pattern per line. Requests arriving from matching referrers bypass the cache. Useful for excluding traffic from specific third-party domains that requires fresh, non-cached content.

Logged-in User Handling

Configure how Prime Cache responds to authenticated WordPress users.

WooCommerce Auto-Exclusion

When WooCommerce is installed, the following pages are automatically excluded from caching. No configuration is needed.

• Cart page (/cart/) — changes dynamically as items are added or removed
• Checkout page (/checkout/) — payment processing page
• My Account page (/my-account/) — user-specific account information
• Requests with active WooCommerce session cookies (e.g., woocommerce_cart_hash) — visitors with items in their cart

Per-post Metabox

Every post and page edit screen includes a Prime Cache metabox in the sidebar. Use it to disable caching for a single post or page without affecting the rest of your site.

Steps:

1. Open the edit screen for the post or page you want to exclude.
2. Find the Prime Cache block in the right-hand sidebar.
3. Check the Disable cache for this page checkbox.
4. Click Update to save.

File Optimization

Reduce page weight and the number of HTTP requests by optimizing HTML, CSS, and JavaScript output. Configure under Prime Cache > File Optimization.

Overview

File optimization processes WordPress’s HTML output and the CSS/JS files it enqueues. When combined with page caching, the optimized output is cached so the processing cost is paid only once per cache lifetime.

Minify HTML

Removes unnecessary whitespace, comments, and blank lines from HTML output to reduce transfer size.

Minify CSS

Removes comments, line breaks, and redundant whitespace from CSS stylesheets. The minified output is cached, so subsequent requests incur no processing overhead.

Default: Disabled

Minify JavaScript

Removes comments, line breaks, and redundant whitespace from JavaScript files to reduce their transfer size.

Default: Disabled

Remove Query Strings

Strips version query parameters (e.g., ?ver=6.4.2) from CSS and JavaScript URLs. Some proxy servers and CDNs refuse to cache static assets that have query strings in their URLs. Removing the query strings improves cache hit rates for those proxies.

Default: Disabled

Inline Small CSS

CSS files below a configurable size threshold are inlined directly into the HTML as <style> blocks instead of being loaded as external <link> references. This eliminates an HTTP request for each small stylesheet and can reduce render-blocking.

Default: Disabled

Threshold: Set the maximum file size to inline (e.g., 2 KB). CSS files smaller than this value are candidates for inlining.

Async Non-first CSS

Loads all CSS files except the first one asynchronously using the media="print" onload="this.media='all'" pattern. This reduces render-blocking CSS and can improve First Contentful Paint scores.

Default: Disabled

Disable WordPress Emoji

WordPress automatically loads emoji scripts, CSS, and a DNS prefetch tag on every page, even on sites that do not use custom emoji. Modern operating systems and browsers render emoji natively without these files. Enabling this setting removes all three.

Default: Disabled

Enabling this setting removes:

• Emoji JavaScript (wp-emoji-release.min.js)
• Emoji inline CSS in the <head>
• DNS prefetch for the emoji CDN (s.w.org)

Media

Optimize images, iframes, and videos to improve Core Web Vitals scores. Configure under Prime Cache > Media.

Overview

Media optimization targets two Core Web Vitals metrics: Largest Contentful Paint (LCP) and Cumulative Layout Shift (CLS). The Free edition provides lazy loading, skip-first-N image prioritization, missing image dimension injection, control over WordPress’s native lazy loading, and — since version 1.10.0 — WebP conversion with bulk Media Library optimization and a choice of three delivery methods (.htaccess rewrite, <picture> tag, URL rewrite). AVIF conversion, EXIF stripping, on-upload resize, and YouTube thumbnail replacement are provided by the optional add-on.

Lazy Load

Applies the HTML loading="lazy" attribute to images, iframes, and video elements so they are only fetched when the user scrolls them into view. This is native browser lazy loading — no external JavaScript library is required.

Default: Disabled

Elements targeted by lazy loading:

Skip First N Images (LCP Optimization)

Images near the top of the page are likely to be the Largest Contentful Paint element. Lazy-loading them would delay LCP and hurt PageSpeed scores. This setting excludes the first N images from lazy loading and applies fetchpriority="high" to the very first image to signal that it is high priority for the browser.

Skip count: 3 (default) — The first 3 images are excluded from lazy loading. The first image also receives fetchpriority="high".

Add Missing Image Dimensions (CLS Prevention)

Automatically adds width and height attributes to <img> tags that are missing them. When browsers know an image’s dimensions before it loads, they can reserve the correct amount of space in the layout — preventing the page from jumping around as images load (Cumulative Layout Shift). This directly improves your CLS score.

Default: Disabled

Disable WordPress Native Lazy Load

WordPress 5.5 and later adds loading="lazy" to images automatically. If Prime Cache’s Lazy Load setting is enabled, both systems would apply the attribute — which is harmless but redundant. Enable this setting to remove WordPress’s native lazy loading and rely solely on Prime Cache’s implementation (which also covers iframes and videos, unlike the WordPress default).

Default: Disabled

WebP Conversion (Free)

Since version 1.10.0, WebP conversion is part of the Free edition. JPG and PNG images are automatically converted to WebP on upload (all thumbnail sizes included), and existing images can be bulk-converted from the Media tab. Choose between three delivery methods to match your server and theme:

• .htaccess rewrite — Transparently serves WebP at the original image URL when the browser supports it. Fastest, but requires Apache with mod_rewrite.
• <picture> tag — Wraps <img> elements in <picture> with a WebP source. Works on any server (Apache / Nginx / LiteSpeed).
• URL rewrite — Rewrites src / srcset in the rendered HTML to point at the WebP variant for supporting browsers.

The Media tab auto-detects whether your PHP build supports WebP encoding and reports the result. The Media Library list view gets an extra column showing the per-image compression percentage. The Exclude PNG Files option lets you keep transparent PNGs out of the conversion pipeline.

Default: disabled (enable from the Media tab)

Optional Add-on Media Features PRO

The following media optimizations are provided by the optional add-on. The settings UI is not bundled in the Free plugin — installing and activating the add-on surfaces the related controls.

• AVIF Conversion: Adds the AVIF format on top of the Free WebP pipeline. At delivery time the browser receives AVIF / WebP / original automatically depending on its capabilities.
• AVIF Quality Control: Lossy / lossless / custom quality for AVIF output.
• EXIF Data Removal: Strips GPS coordinates and camera metadata for privacy and smaller files.
• Image Resize on Upload: Caps oversized uploads to a maximum width/height.
• YouTube Thumbnail Replacement: Swaps YouTube iframe embeds for a lightweight thumbnail that loads the player only on click.

The full add-on feature list is also visible inside WordPress at Prime Cache > Pro Features (a dedicated information page introduced in version 1.10.14). See the Pro Manual for full details.

Preload

Warm the page cache in the background so that even first-time visitors receive cached responses. Configure under Prime Cache > Preload.

Overview

Preloading visits pages on your behalf in the background to generate and store cache files before any real visitor requests them. This means there is no “cold cache” period after a purge — the next visitor gets a cached response immediately.

Cache Preloading

Background-crawls key pages and stores their HTML in the cache. In the Free edition, the following pages are preloaded.

• Homepage: The site’s front page.
• All published posts and pages: Every piece of content with a “published” status.

Preload triggers:

Pro-only Preload Features PRO

The following advanced preloading features are available exclusively in the Pro edition.

• Sitemap Preloading: Automatically discovers all URLs from your XML sitemap and preloads each one.
• Link Prefetching: JavaScript-based hover and viewport-intersection detection fetches pages in the background before the user clicks.
• Speculation Rules API: Uses the Chrome 109+ Speculation Rules API to prerender pages when the user is likely to navigate to them, making page transitions nearly instant. Non-supporting browsers simply ignore the rules.
• Font Preloading: Auto-detects @font-face declarations and injects <link rel="preload"> tags for each font file.
• LCP Optimization: Sets fetchpriority="high" and <link rel="preload"> for hero images to improve Largest Contentful Paint.
• DNS Prefetch / Preconnect: Early DNS resolution and TCP+TLS handshakes for external domains used by your site.
• Manual Resource Preloading: Add specific URLs to a preload list with auto-detected resource type.

Performance Tweaks

Reduce page weight by disabling WordPress features you do not need. Configure under Prime Cache > Performance Tweaks.

Overview

WordPress outputs a number of scripts, styles, and meta tags by default that are not necessary on every site. Each tweak below is independent — enable only the ones that apply to your site. Test your site after enabling each one to confirm nothing breaks.

Scripts & Styles

WordPress Features

WooCommerce

Auto Purge

Prime Cache automatically removes cache files when WordPress content changes, so visitors always see up-to-date content without requiring manual cache management.

Overview

Auto Purge hooks into WordPress events and invalidates the relevant cached files when those events fire. No configuration is required — it works automatically from the moment page caching is enabled. When a post is published, only that post’s cached file is removed (smart purge). You can always purge the entire site cache from the admin bar if needed.

Trigger List

Tools

Back up, restore, and diagnose your Prime Cache configuration. Access all tools under Prime Cache > Tools.

Overview

The Tools tab provides settings import/export, factory reset, system information, debug logging, compatibility checking, and WP-CLI integration.

Import / Export Settings

Export all current settings to a JSON file, or import a previously exported file to restore or replicate a configuration.

Export steps:

1. Open Prime Cache > Tools.
2. Click Export Settings.
3. A JSON file is downloaded automatically (e.g., prime-cache-settings-2026-01-01.json).

Import steps:

1. Click Choose File and select a previously exported JSON file.
2. Click Import Settings.
3. Reload the page after import to see the restored settings.

Common use cases:

• Site migration: Transfer settings from a staging environment to production.
• Pre-change backup: Save your current state before experimenting with new settings.
• Multi-site deployment: Apply the same configuration to several WordPress installations.

Reset to Defaults

Reverts all Prime Cache settings to their factory defaults. Use this when troubleshooting an issue or when you want to start fresh.

What is reset:

• All plugin settings
• Cache exclusion lists (URL, cookie, user-agent, referrer)
• File optimization settings
• Media settings
• Performance tweak settings

What is NOT reset:

• Existing cache files (use Purge All Cache from the admin bar to delete them)
• advanced-cache.php (removed only when the plugin is deactivated or deleted)

System Information

Displays a comprehensive snapshot of your server and WordPress environment. Use this when troubleshooting issues or when asking for support.

Information displayed:

Debug Logging

When enabled, Prime Cache logs cache operations — file writes, cache hits, cache misses, purge events, and skip reasons — to a log file. Use this to diagnose why certain pages are not being cached or why cache files are being purged unexpectedly.

Log file location: wp-content/cache/prime-cache/debug.log

Compatibility Check

Scans your installed plugins and warns you if any known conflicting caching plugins are active. Prime Cache checks for 14 popular caching plugins.

Examples of detected plugins:

• W3 Total Cache
• WP Super Cache
• WP Fastest Cache
• LiteSpeed Cache
• SiteGround Optimizer
• Autoptimize
• Hummingbird
• Swift Performance
• Other major caching plugins

WP-CLI Support

Prime Cache registers a wp prime-cache WP-CLI command group for command-line cache management. This is useful in deployment scripts, cron jobs, and CI/CD pipelines.

Available commands:

Usage examples:

# Delete all cache files
wp prime-cache flush

# Preload cache for homepage and published posts
wp prime-cache preload

# Check cache status and statistics
wp prime-cache status

Deployment script example:

#!/bin/bash
# Update WordPress and refresh cache
wp plugin update --all
wp theme update --all
wp prime-cache flush
wp prime-cache preload
echo "Deploy complete: cache purged and preloaded."

Pro Version Features

Prime Cache Pro adds the following advanced features on top of everything in the Free edition.

File Optimization — Pro Features PRO

• Combine CSS: Merges multiple CSS files into a single file to reduce HTTP requests.
• Combine JavaScript: Merges multiple JS files into a single file.
• Defer JavaScript: Adds the defer attribute to script tags to eliminate render-blocking JS.
• Delay JavaScript: Delays all JS execution until the first user interaction (scroll, click, touch) — particularly effective on mobile. Requires mobile-separate cache.
• Delay JS Safe Mode: Delays only external (third-party) scripts while leaving first-party scripts unaffected.
• Critical CSS: Auto-generates or accepts manually defined above-the-fold CSS, inlined in the HTML head for instant first paint.
• Remove Unused CSS: Analyzes each page and strips CSS rules that are not used on that page.
• Local Google Analytics: Downloads and self-hosts gtag.js / analytics.js from your own server for privacy and performance.
• Google Fonts Optimization: Combine, self-host, or add display=swap to Google Fonts requests.

Media Optimization — Add-on Features PRO

• AVIF Conversion: Adds AVIF on top of the Free WebP pipeline. Delivery automatically picks AVIF / WebP / original based on browser support.
• AVIF Quality Control: Lossy, lossless, or custom quality for AVIF output.
• YouTube Thumbnail Replacement: Replaces iframe embeds with a lightweight click-to-play thumbnail.
• EXIF Data Removal and Image Resize on Upload: Strips metadata and caps oversized uploads.

Caching — Pro Features PRO

• Object Cache: Persistent object caching with APCu, Redis, or Memcached backends.
• CDN URL Rewriting: Serve static assets from any pull-zone CDN with optional domain sharding.
• Cloudflare Integration: Automatic zone purge and per-URL purge via the Cloudflare API.
• Varnish Integration: HTTP PURGE requests with regex support.
• Sucuri Integration: Firewall cache sync via API.

Database Optimization PRO

• Bulk delete: revisions, auto-drafts, trashed posts, spam/trashed comments, expired transients, all transients
• OPTIMIZE TABLE to defragment database tables
• Automatic scheduled cleanup (daily, weekly, or monthly via WP-Cron)

Security Headers PRO

• HSTS (HTTP Strict Transport Security) with configurable max-age
• X-Content-Type-Options, X-Frame-Options, X-XSS-Protection
• Referrer-Policy, Permissions-Policy

Other Pro Features PRO

• Heartbeat API Control: Per-location (frontend, admin dashboard, post editor) management with Disable, Reduce Frequency, and Custom Interval modes.
• Advanced Preloading: Sitemap preloading, Speculation Rules API, link prefetching, font preloading, LCP preload, DNS prefetch/preconnect, manual resource preloading.

The complete add-on feature list is also visible inside WordPress at Prime Cache > Pro Features (the dedicated information page introduced in version 1.10.14). For pricing and availability, visit the Prime Cache product page.

Frequently Asked Questions

Server Requirements

Q: What are the minimum server requirements?

WordPress 5.8 or later, PHP 7.4 or later (tested up to WordPress 7.0). WebP conversion (Free, since 1.10.0) and AVIF conversion (Pro add-on) require either the GD or Imagick PHP extension. For object caching (Pro add-on), APCu, Redis, or Memcached must be available.

Plugin Conflicts

Q: Can I run Prime Cache alongside another caching plugin?

No. Running two caching plugins at the same time causes conflicts and can break your site. Prime Cache’s Compatibility Check automatically detects and warns about 14 known caching plugins. Deactivate any other caching plugins before using Prime Cache.

Nginx Support

Q: Does Prime Cache work on Nginx?

Yes. Page caching, file optimization, media optimization, and all other PHP-based features work on any web server, including Nginx. The .htaccess Optimization feature is Apache-specific and should be left disabled on Nginx — all other features work normally.

WooCommerce Support

Q: Is Prime Cache compatible with WooCommerce?

Yes. The WooCommerce cart, checkout, and My Account pages are automatically excluded from caching. Additional WooCommerce optimizations (suppress WooCommerce scripts on non-WooCommerce pages, disable cart fragments AJAX) are available under Performance Tweaks.

Clearing the Cache

Q: How do I clear the cache?

There are several ways:

• Admin bar: Click Prime Cache in the admin bar and choose from more than ten purge actions.
• Dashboard: Use the quick-action buttons on the Prime Cache Dashboard tab.
• WP-CLI: Run wp prime-cache flush from the command line.
• Auto Purge: Cache is purged automatically on post publish/update and other WordPress events.

Disabling Cache for a Specific Page

Q: Can I disable caching for a specific post or page?

Yes. Open the post or page in the WordPress editor and check Disable cache for this page in the Prime Cache metabox in the sidebar. Alternatively, add the URL to the URL exclusion list under Page Cache > Exclusions.

WordPress Multisite

Q: Does Prime Cache support WordPress multisite?

Page caching is not supported on multisite installations. All other features — file optimization, lazy loading, image dimensions, CDN integration (Pro), image optimization (Pro) — work normally on multisite networks.

.htaccess Fast-path Conditions

Q: Under what conditions does the PHP-less .htaccess fast-path apply?

The .htaccess fast-path (which bypasses PHP entirely) applies only when ALL of the following conditions are met. Requests that do not qualify are handled by the PHP dropin, which is still very fast.

• The request is a GET request
• The URL has no query string
• No Vary Cookies are configured
• The URL path contains only ASCII characters
• The visitor is not logged in (no wordpress_logged_in_* cookie present)