Cloudflare cache

Cloudflare cache clears pages from Cloudflare's cache after you change the site, so visitors do not keep getting old pages. You need it only when Cloudflare caches whole HTML pages, through Automatic Platform Optimization (APO) or a Cache Everything rule. Cloudflare caches static files such as images on its own; this module is about pages.

A changed post clears its own page and the listings it appears on. Site-wide changes, such as menus, widgets, themes and plugins, clear everything. The API token and zone ID live in wp-config.php, never in the database.

Module ID	cloudflare
Default	Off
Available	When SHOUSE_CLOUDFLARE_TOKEN and a valid SHOUSE_CLOUDFLARE_ZONE are in wp-config.php. Until then SafeHouse shows "Add SHOUSE_CLOUDFLARE_TOKEN (an API token allowed only to purge this zone's cache) and SHOUSE_CLOUDFLARE_ZONE (the zone ID from the Cloudflare dashboard) to wp-config.php."
WP-CLI	wp shouse cloudflare purge (only while the module runs)
Since	0.1.0

How it works

What a change clears

Change	What is cleared
Publishing a post, page or other public post type, or saving one that is already published	That post's addresses (below)
A comment that is approved, and any change to a comment's status or text	The addresses of the comment's post
A WooCommerce stock or stock status change	The addresses of the product (for a variation, its parent product)
Unpublishing, trashing or deleting a published post	Everything
Switching the theme, saving the Customizer, saving a menu, changing widgets	Everything
Installing or updating WordPress, a plugin or a theme through the WordPress updater; activating or deactivating a plugin	Everything
Any save of SafeHouse settings, including wp shouse module enable and wp shouse module disable for any module	Everything
Another plugin firing the litespeed_purge_all action. Maintenance mode does this when it is switched on or off	Everything
Clear the whole Cloudflare cache or wp shouse cloudflare purge	Everything

A post's addresses are:

• the home page;
• the post's own address;
• the archive of its post type, if the type has one;
• for blog posts, the page set as the posts page in Settings → Reading;
• the archive of every term the post has in every public taxonomy, such as its categories and tags.

Not included: feeds, further pages of an archive (/page/2/), author and date archives, and addresses with a query string. Cloudflare keeps those until they expire there or until something clears everything.

SafeHouse sends at most 30 addresses in one call. When a batch holds more, it clears everything instead. A batch is either what one request changed (a bulk edit can pass 30) or the whole queue the cron event sends.

Timing of calls

1. During a request, SafeHouse collects the changed addresses.
2. At the end of the request, it sends one call to the Cloudflare API with all of them.
3. If the previous call was less than 30 seconds ago, it sends nothing. It adds the addresses to a queue and schedules one WordPress cron event, shouse_cloudflare_purge, 30 seconds later. That event sends everything in the queue in one call.

Every call starts the 30 seconds again, including a call that failed. A cron event runs when WordPress cron next runs after it is due, so on a site with little traffic, or with DISABLE_WP_CRON and a system cron, it can come later than 30 seconds.

Changes made with WP-CLI are sent at the end of the command. Unlike the LiteSpeed page cache, they do not wait for a web request.

Clear the whole Cloudflare cache and wp shouse cloudflare purge call Cloudflare at once, without waiting for the 30 seconds.

The API call

SafeHouse sends POST https://api.cloudflare.com/client/v4/zones/ZONE_ID/purge_cache with the header Authorization: Bearer and the token, and waits at most 5 seconds for the answer. The body lists the addresses, for example:

{"files":["https://example.com/","https://example.com/hello-world/","https://example.com/category/news/"]}

or, to clear everything:

{"purge_everything":true}

api.cloudflare.com is the only host the module contacts. A failed call never stops the save or the page that caused it. The result goes to the module's panel, the activity log and, after a failure, Site Health.

Settings

The module has no settings in wp-admin. It reads two constants from wp-config.php.

Constant	Default	What it does
SHOUSE_CLOUDFLARE_TOKEN	None	The Cloudflare API token. Spaces around it are ignored.
SHOUSE_CLOUDFLARE_ZONE	None	The zone ID: 32 hexadecimal characters, upper or lower case. Any other value counts as missing, and the module stays Unavailable with the message above.

While the module runs, Details shows the last call and the Clear the whole Cloudflare cache button. The line reads one of:

• "Nothing cleared yet."
• "Last cleared DATE (everything)." or "Last cleared DATE (3 addresses)."
• "The last call on DATE failed: ERROR"

Set up the Cloudflare cache

Create an API token

SafeHouse needs a token that can only clear this zone's cache. If wp-config.php ever leaks, such a token cannot change anything else in your Cloudflare account.

1. In the Cloudflare dashboard, open API Tokens and select Create Token.
2. Under Custom Token, select Get started.
3. Give the token one permission: Zone → Cache Purge.
4. Limit the token's zone resources to this site's zone only.
5. Create the token and copy it.

Find the zone ID

1. In the Cloudflare dashboard, select the site's domain.
2. On the domain's Overview page, find the API section.
3. Copy the Zone ID.

Add the constants

Add both lines to wp-config.php, with your token and zone ID:

define( 'SHOUSE_CLOUDFLARE_TOKEN', 'YOUR_API_TOKEN' );
define( 'SHOUSE_CLOUDFLARE_ZONE', '0123456789abcdef0123456789abcdef' );

Switch the module on

1. Go to SafeHouse → Modules → Cloudflare cache.

   The badge shows Off instead of Unavailable once both constants are valid.

2. Turn on the switch.

3. Select Save Changes.

4. Select Details.

5. Select Clear the whole Cloudflare cache.

   SafeHouse shows "Cloudflare cache cleared." when the token and zone ID work.

With WP-CLI, wp shouse module enable cloudflare switches the module on, and wp shouse cloudflare purge tests the token.

The Integrations tab then shows "cache clearing" as on in the Cloudflare row.

Clear the whole cache

In wp-admin:

1. Go to SafeHouse → Modules → Cloudflare cache and select Details.

2. Select Clear the whole Cloudflare cache.

   SafeHouse shows "Cloudflare cache cleared." or "Cloudflare refused: ERROR".

With WP-CLI:

wp shouse cloudflare purge

The command prints Success: Cloudflare cache cleared. or Error: Cloudflare refused: ERROR.

Fix a refused call

A failed call shows in three places:

• the module's Details: "The last call on DATE failed: ERROR";
• the activity log, as a warning cloudflare_purge_failed: "Cloudflare cache could not be cleared: ERROR";
• Tools → Site Health, as a recommended improvement "Cloudflare refused to clear the cache": "Visitors may see old pages until the cache expires. Check the token and zone ID in wp-config.php. Cloudflare said: ERROR". This result appears only while the last call failed. The next successful call removes it.

ERROR is one of:

• the WordPress HTTP error, for example when api.cloudflare.com did not answer within 5 seconds;
• HTTP CODE: MESSAGE, with the status code and the first error message Cloudflare returned;
• HTTP CODE: unknown error, when Cloudflare's answer had no error message.

If Cloudflare refuses, check that the token has the Zone → Cache Purge permission for this zone and that SHOUSE_CLOUDFLARE_ZONE is this site's zone ID. A failed call from the cron queue is not retried. After fixing the cause, clear the whole cache once.

What it stores

• Option shouse_cloudflare_result (not autoloaded): the time of the last call, the number of addresses (0 means everything) and the error, up to 300 characters.
• Option shouse_cloudflare_pending (not autoloaded): addresses waiting for the cron event.
• Transient shouse_cloudflare_last: marks a call in the last 30 seconds.
• Cron event shouse_cloudflare_purge: scheduled once, 30 seconds ahead, when calls pile up.
• Activity log entries: cloudflare_purged ("Cloudflare cache cleared: everything" or "Cloudflare cache cleared: 3 addresses") and cloudflare_purge_failed.

SafeHouse never stores the token. It reads it from wp-config.php and does not write it to the log. Uninstalling SafeHouse deletes the options and the transient.

Limitations

• Only the addresses listed above are cleared for a post. Feeds, /page/2/ and later pages, author and date archives, and query-string variants keep the old version until they expire on Cloudflare or until everything is cleared.
• Every SafeHouse settings save clears everything, even an unrelated one such as a change of alert recipients.
• A batch of more than 30 addresses clears everything, whether it comes from one request or from the queue the cron event sends.
• A failed call also starts the 30-second wait, and a failed call from the cron queue is dropped.
• Queued changes depend on WordPress cron and can take longer than 30 seconds.
• Changes outside the table above do not clear anything, for example editing a category name or a user. WooCommerce can save a price change without updating the product post, for example through its REST API or when a scheduled sale starts; such a change may not clear the product's page. If you rely on it, test it on a staging site.
• The module does not configure Cloudflare. APO, Cache Rules and any bypass for logged-in users or carts are set up in Cloudflare.
• One site clears one zone.
• Deactivating or uninstalling SafeHouse does not remove a shouse_cloudflare_purge event that is still scheduled. It does nothing when it runs without SafeHouse.

Related pages

• Behind Cloudflare or a proxy
• LiteSpeed page cache
• Maintenance mode
• Configure in wp-config
• Configuration constants
• Command line reference