Server Configuration

You do not need to read this to use the plugin. Read it if you want to know exactly what changed on your server, if a write was refused, or if you run NGINX, LiteSpeed or IIS.

Everything Caching Out touches, at a glance

Pro's Image compression is the only feature that changes files in your uploads, and only for an image you choose to compress; see Image compression. Apart from that, nothing else on your server is modified. Caching Out never edits your theme, never edits another plugin's files, and never deletes a file it did not write.

---

Apache

The three blocks written to .htaccess

On activation, and again whenever you save the Browser Caching tab, Caching Out writes up to three marker-delimited blocks into the .htaccess file in your WordPress root folder. Each block corresponds to one setting on the Browser Caching tab and is written only while that setting is on:

• # BEGIN WP Caching Out Expires – far-future expiry dates for static files, so returning visitors do not download them again.
• # BEGIN WP Caching Out GZIP – GZIP compression for text files.
• # BEGIN WP Caching Out Brotli – Brotli compression for text files, used by servers that have the Brotli module.

Every block is wrapped in an <IfModule> guard, so if your server does not have the matching Apache module the rules are ignored rather than causing an error. This is the Expires block exactly as written:

# BEGIN WP Caching Out Expires
<IfModule mod_expires.c>
ExpiresActive On
ExpiresByType image/jpeg "access plus 1 year"
ExpiresByType image/gif "access plus 1 year"
ExpiresByType image/png "access plus 1 year"
ExpiresByType image/webp "access plus 1 year"
ExpiresByType image/svg+xml "access plus 1 year"
ExpiresByType image/x-icon "access plus 1 year"
ExpiresByType image/avif "access plus 1 year"
ExpiresByType video/mp4 "access plus 1 month"
ExpiresByType video/webm "access plus 1 month"
ExpiresByType audio/mpeg "access plus 1 month"
ExpiresByType audio/ogg "access plus 1 month"
ExpiresByType text/css "access plus 1 year"
ExpiresByType text/javascript "access plus 1 year"
ExpiresByType application/javascript "access plus 1 year"
ExpiresByType font/woff2 "access plus 1 year"
ExpiresByType font/woff "access plus 1 year"
ExpiresByType application/font-woff "access plus 1 year"
ExpiresByType application/font-woff2 "access plus 1 year"
ExpiresByType application/vnd.ms-fontobject "access plus 1 year"
ExpiresByType application/x-font-ttf "access plus 1 year"
</IfModule>
# END WP Caching Out Expires

The GZIP and Brotli blocks each add one AddOutputFilterByType line for HTML, CSS, JavaScript, JSON, XML, RSS, SVG and font files, inside a mod_deflate or mod_brotli guard.

Where in the file

If your .htaccess contains a # BEGIN WordPress block, the Caching Out blocks are inserted directly above it. Otherwise they are appended to the end of the file. Your own rules are never reordered or rewritten.

If there is no .htaccess file at all, Caching Out creates an empty one first, provided the WordPress root folder is writable.

Backup and revert

Before every write, Caching Out copies .htaccess to a file next to it named .htaccess.cachingout-backup-<date>-<time>. If the write succeeds the backup is deleted. If anything goes wrong, the backup is deliberately left in place as your recovery point, and the message you see names its exact path.

The generated file is also checked before it is saved. A single unrecognised word in .htaccess makes Apache return an error for every page on the site, including wp-admin, so Caching Out refuses to save a result that contains a directive with no argument, and your original file is left exactly as it was.

To remove the blocks yourself at any time, delete each block from its # BEGIN WP Caching Out ... line to its matching # END ... line. Take your own backup first.

When Caching Out refuses to write

Caching Out will not write to .htaccess when:

• Another caching plugin's rules are present. If a block such as # BEGIN W3TC, # BEGIN WPSuperCache, # BEGIN LSCACHE, # BEGIN WP Fastest Cache, # BEGIN WP Rocket or # BEGIN Breeze still contains rules, the write is refused and the message names the block. Two plugins' rules in one file is how sites break. Remove that block first. An empty marker pair with nothing between the BEGIN and END lines does not block the write.
• The file or the root folder is not writable. The message tells you the path and asks you to add the rules by hand.

Either way, page caching still works: it does not depend on .htaccess. Only browser caching and compression do.

---

NGINX

NGINX does not read .htaccess files, so nothing can be written for you. Page caching still works, because it runs inside PHP through the advanced-cache.php drop-in. Browser caching and compression have to be added to your server configuration by hand, once.

Add this to your server block (or ask your host to), then reload NGINX:

# ---- WP Caching Out: Browser Caching & Compression ----
# Add this to your server block (or a location block).
#
# 1. Far-future Expires / Cache-Control for static assets.
location ~* \.(css|js|png|jpg|jpeg|gif|webp|svg|woff|woff2|ttf|eot|ico|xml|mp4|webm|ogg)$ {
    expires 1y;
    add_header Cache-Control "public, immutable";
}

# 2. GZIP compression for text-based assets.
gzip on;
gzip_types text/html text/css text/javascript application/javascript application/json application/xml text/xml application/rss+xml image/svg+xml application/x-font-ttf application/x-font-opentype application/vnd.ms-fontobject;

# 3. Brotli compression (requires brotli module).
# brotli on;
# brotli_types text/html text/css text/javascript application/javascript application/json application/xml text/xml application/rss+xml image/svg+xml;
# ---- End WP Caching Out ----

The Brotli lines are commented out because Brotli needs a module that not every NGINX build includes. Uncomment them only if your host confirms the module is available. Leaving the Browser Caching settings switched on in the plugin does no harm on NGINX; they simply have nothing to write to.

Image compression backups (Pro)

If you compress images with Caching Out Pro, the exact originals are kept in wp-content/cachingout-images/backup/. On Apache and LiteSpeed that folder is blocked from the web automatically; NGINX ignores the rule, so add this to your server block as well:

location ^~ /wp-content/cachingout-images/backup/ { deny all; }

The WebP and AVIF copies in wp-content/cachingout-images/ must be sent as image/webp and image/avif. On Apache and LiteSpeed Caching Out writes a small .htaccess there that says so, because some older Apache builds do not know either type and would label photo.jpg.webp as a JPEG. NGINX uses its own mime.types; if yours has no image/webp or image/avif line (older builds lack avif), add this as well (the backup/ rule above still applies, because NGINX picks the longer match):

location ^~ /wp-content/cachingout-images/ {
    types { image/webp webp; image/avif avif; }
}

LiteSpeed

LiteSpeed reads Apache .htaccess files, so Caching Out writes its blocks in the same way it does on Apache and they take effect. This path is expected to work but has not been independently verified on our test matrix; see compatibility-matrix.md.

If you also have the LiteSpeed Cache plugin installed, do not run both page caches at once. Deactivate one of them.

IIS (Windows)

IIS uses web.config rather than .htaccess. Caching Out does not generate web.config rules, so browser caching and compression must be configured in IIS by you or your host. The advanced-cache.php drop-in that does the page caching is platform-agnostic and works normally.

---

The advanced-cache.php drop-in and WP_CACHE

These two pieces are what make a cached page fast.

wp-content/advanced-cache.php is a WordPress "drop-in": a file WordPress loads very early, before your theme and your other plugins. On a cache hit it sends the stored HTML straight from disk and stops. That is why a cached page costs so little: WordPress never finishes loading.

WP_CACHE is a line added near the top of wp-config.php:

/** Enable WP Caching Out page cache. */
define( 'WP_CACHE', true );

WordPress only loads the drop-in when this constant is true. Without it, the drop-in file sits on disk and does nothing. Before changing wp-config.php, Caching Out copies it to a hidden backup file in the same folder, and it refuses to write at all if the file is not writable, telling you the line to add by hand. Some managed hosts overwrite wp-config.php on their own schedule; if WP_CACHE keeps disappearing, that is usually the cause, and your host can add the line for you.

Ownership: Caching Out only touches a drop-in it wrote

There is only one advanced-cache.php slot in WordPress, and every page caching plugin wants it. Caching Out follows one rule with no exceptions:

It writes, overwrites or deletes advanced-cache.php only when the file on disk is byte-for-byte the copy Caching Out itself installed.

When it writes the drop-in it records a fingerprint of the exact content, and before touching the file again it compares the file on disk against that fingerprint. Anything else, whether it belongs to a plugin Caching Out recognises or is completely unknown, is treated as someone else's file and left alone. What you see in each case:

• A drop-in from another caching plugin was already there. Page caching is switched off and reported as blocked, and the plugin name is shown. Every other part of Caching Out keeps working. To hand the slot over, deactivate the other caching plugin, then deactivate and reactivate Caching Out.
• The drop-in was replaced after Caching Out installed it. The Filesystem Check reports that the file does not match the copy Caching Out installed. Use "Re-run filesystem check" to reinstall it if it is meant to be ours, or look for another caching plugin.
• The drop-in cannot be deleted on deactivation. It is left in place and the reason is written to your PHP error log. Delete it manually if you need to.

Caching Out never reads, writes or removes object-cache.php. Object caching is outside its scope entirely, and a Redis or Memcached drop-in installed by your host or another plugin is not affected.

---

The cache directory

Cached pages live in:

wp-content/cache/cachingout/

The folder is created the first time a page is cached, and it is recreated whenever you purge. Two guard files are placed inside it: an index.php that stops directory listing, and an .htaccess that stops PHP files in that folder being executed. The .htaccess guard only has an effect on Apache and LiteSpeed; on NGINX and IIS the index.php guard is what applies.

The same folder also holds the runtime settings snapshot the drop-in reads. That snapshot is rewritten every time you save any settings page, which is why "save any settings page once" fixes so many problems. Cached pages are always written to a temporary file first and then renamed into place, so a visitor can never receive a half-written page.

File permissions Caching Out needs

The web server user has to be able to write these, which is the normal setup on most hosts. Caching Out never changes permissions itself, and it aborts cleanly rather than writing part of a file.

---

What happens on deactivation

Deactivation is deliberately minimal, so that switching the plugin off can never take a site down. It does exactly two things:

1. Deletes wp-content/advanced-cache.php, but only if the file is still the copy Caching Out installed.
2. Unschedules the plugin's background tasks.

It does not edit wp-config.php and does not edit .htaccess. The WP_CACHE line is left in place, which is harmless: WordPress only acts on it when a drop-in file exists, and that file is now gone. The browser caching and compression rules also stay, so your static files keep their cache headers.

If you want those removed without uninstalling, delete the # BEGIN WP Caching Out ... blocks from .htaccess yourself, and remove the WP_CACHE line from wp-config.php. Back both files up first.

What happens on uninstall

Deleting the plugin from the Plugins screen runs the full cleanup:

• The advanced-cache.php drop-in is removed, if it is ours.
• wp-content/cache/cachingout/ is deleted with everything in it.
• All four # BEGIN WP Caching Out ... blocks are removed from .htaccess.
• The WP_CACHE line is removed from wp-config.php.
• Background tasks, saved settings, temporary values and per-user preferences are deleted.

On a multisite network this runs for every site in the network.

---

Leftovers from a previous cache plugin

Deactivating and deleting another caching plugin rarely removes everything it created. Caching Out looks for the leftovers, names them, and tells you whether they are safe to delete. It never deletes another plugin's files.

Open Caching Out > Filesystem Check and look at the row "Leftovers from other cache plugins". The Page Audit reports the same findings as advice. Only plugins that are no longer installed are reported: while a plugin is still installed, its files are its own business.

What is looked for:

• Empty marker pairs in .htaccess, such as # BEGIN LSCACHE directly followed by # END LSCACHE. These do nothing. Deleting the two lines is safe and tidies the file.
• A marker block that still contains rules. Apache keeps applying those rules, and Caching Out will not write its own browser caching rules while they are there. Back up .htaccess, delete the block from its # BEGIN line to its # END line, then save the Browser Caching tab again.
• Folders left under wp-content, such as litespeed, w3tc-config, wp-rocket-config, breeze-config, wphb-cache and wpo-cache, plus stale cache folders under wp-content/cache/ such as supercache, all, page_enhanced, minify, wp-rocket, critical-css, used-css, breeze-minification, autoptimize and comet-cache.
• Configuration files such as wp-content/wp-cache-config.php.

The plugins currently recognised are LiteSpeed Cache, W3 Total Cache, WP Rocket, WP Super Cache, WP Fastest Cache, Breeze, Hummingbird, Cache Enabler, Swift Performance, Comet Cache, Autoptimize and WP-Optimize.

Each finding is listed with its exact path and one line saying what it is. Delete them with your file manager or FTP client once you have confirmed the plugin really is uninstalled.

More detail: kb/02-browser-caching.md.

---

Checking the result

Caching Out > Filesystem Check shows the state of everything described here: the WP_CACHE constant, the drop-in and who owns it, the settings snapshot, the cache directory and its guards, and any leftovers from a previous cache plugin. Each row says what was found and, if something is wrong, what to do about it. See troubleshooting.md.