Skip to content

Getting started#

Requirements#

  • WordPress 6.0 or later, PHP 7.4 or later (from the plugin header).
  • wp-content writable by the PHP user. The cache lives in wp-content/cache/bb-cache.
  • wp-config.php writable by the PHP user if you want WP_CACHE set for you.
  • The plugin folder must be wp-content/plugins/bb-cache. The drop-in includes WP_CONTENT_DIR . '/plugins/bb-cache/inc/serve.php', and serve.php locates the cache folder relative to its own path. A renamed folder (for example bb-cache-main from a repository zip) leaves the drop-in with nothing to include.

Install#

  1. Deactivate any other page cache plugin (see Running alongside or replacing another cache plugin).
  2. Upload the zip under Plugins → Add New → Upload Plugin, or copy the folder to wp-content/plugins/bb-cache.
  3. Activate.

What activation does (BB_Cache_Install::activate()):

Step Result
Create folders wp-content/cache/bb-cache/pages, wp-content/cache/bb-cache/min, and an index.php in cache/bb-cache
Write the config file wp-content/cache/bb-cache/config.php: the page-cache rules the drop-in needs, since it runs before the options table is available
Install the drop-in wp-content/advanced-cache.php, a copy of advanced-cache.tpl.php. Skipped when the existing file belongs to another plugin
Set WP_CACHE define( 'WP_CACHE', true ); // BB Cache in wp-config.php. An existing WP_CACHE line is rewritten; otherwise the line is added directly after <?php. Skipped when the file is not writable
.htaccess The rewrite block is written only if the htaccess_rules setting is already on

Deactivation removes the drop-in (only if it is BB Cache's), sets WP_CACHE to false (only on a line marked BB Cache or WP Rocket; anyone else's line is left alone), removes the .htaccess block, clears the bb_cache_sweep, bb_cache_preload_batch and bb_cache_preload_daily cron events, and empties the page cache.

Uninstalling (deleting the plugin) removes the options bb_cache_settings, bb_cache_img_dims, bb_cache_preload_queue, bb_cache_last_purge and bb_cache_cf_log, and deletes wp-content/cache/bb-cache.

First configuration#

Open Settings → BB Cache. The line under the title shows the number of cached pages and three states:

State Good value Meaning of the others
Drop-in ok missing: no advanced-cache.php. stale: BB Cache's file, but not identical to the current template. foreign: another plugin's file
WP_CACHE on off: the constant is not true, so WordPress never loads the drop-in
.htaccess rules ok or absent absent: block not written (the default). stale: block differs from what the current settings generate. missing: no .htaccess file

Then:

  1. Review the site-specific defaults. exclude_js, delay_js_exclusions, exclude_lazyload, critical_inline and content_visibility_selectors ship with values from the originating site. Clear or replace them. See the settings reference.
  2. Check the bypass lists on the Page cache tab: URIs, cookie name prefixes and user agents that must never be cached. The defaults cover WordPress logins, password-protected posts, commenters and WooCommerce cart, checkout and account pages.
  3. Decide on the mobile cache. cache_mobile is on by default and keeps a second file per URL for phone user agents. Turn it off if the theme prints the same HTML for every device, and always turn it off if a CDN will cache the HTML (see Cloudflare).
  4. Enable optional features one at a time and check the page after each: defer JS, delay JS, lazy loading, the Boost tab.

Saving any tab writes the option and config.php, writes or removes the .htaccess block to match the setting, and purges both the page cache and the minified files.

Verifying with the X-BB-Cache header#

Front-end responses carry an X-BB-Cache header while the page cache is on and the drop-in is installed.

curl -s -o /dev/null -D - https://example.com/ | grep -i x-bb-cache

Use a GET request as shown. curl -I sends HEAD, which the drop-in never caches, so it always reports MISS (method).

Header Meaning
X-BB-Cache: HIT Served from the page cache by the PHP drop-in
X-BB-Cache: HIT (htaccess) Served by the Apache rewrite block without starting PHP
X-BB-Cache: MISS (miss) No file yet. This response is stored if it qualifies; the next request should be a HIT
X-BB-Cache: MISS (expired) The file was older than the lifespan and was deleted. This response replaces it
X-BB-Cache: MISS (<other>) The request must not be cached. The reasons are listed in Troubleshooting
no header The drop-in did not run, or the page cache is off. See Troubleshooting

A stored page ends with the comment <!-- Cached by BB Cache on YYYY-MM-DD HH:MM:SS UTC -->.

Remember that requests with a session cookie are bypassed. A browser where you are logged in to WordPress shows MISS (cookie); test in a private window or with curl.

Debug query flags#

Flag Effect
?bb_raw=1 The output buffer is not started: no optimiser runs and nothing is stored. Shows the HTML WordPress produced
?bb_nocache=1 The page cache is bypassed for this request (MISS (query)), but the optimisers still run

Comparing the two on the same URL separates "the optimisers changed something" from "the cache served something old". Both flags are unknown query strings to the cache, so neither response is stored.

Optimisers do not run for logged-in users unless optimize_logged_in is on, so check optimiser output while logged out.

Running alongside or replacing another cache plugin#

Run one page cache plugin only. Two plugins would fight over wp-content/advanced-cache.php and WP_CACHE.

BB Cache detects these active plugins and shows an error notice (and a warning in wp bb-cache status) while any of them is active: WP Rocket, Breeze, W3 Total Cache, WP Super Cache, LiteSpeed Cache, WP Fastest Cache, Autoptimize, Cache Enabler.

To replace another plugin:

  1. Deactivate the other plugin. Most remove their own drop-in on deactivation.
  2. Activate BB Cache.
  3. If the notice says advanced-cache.php belongs to another plugin, the old drop-in was left behind. Use replace the drop-in in the notice, Tools → Reinstall advanced-cache.php and set WP_CACHE, or wp bb-cache config. All three overwrite the file.
  4. Verify with the header as above.

BB Cache never overwrites a foreign drop-in on activation; it only does so when you ask through one of those three actions.

A server-level cache in front of PHP (Varnish, a CDN) is not a conflict. See Hosting notes and Cloudflare for how purges reach them.