Docs

Cache and hosting

Last updatedView as Markdown

The Convergence Cache module gives every site one cache-clearing interface regardless of host. This guide covers how a hosting provider is detected, how the module resolves which cache managers to use, and how to clear caches from PHP, REST, or the admin bar.

Host detection

Mantle\Helper\HostingProvider::detect_provider() sniffs host-specific markers in a fixed order and returns the first match, or unknown.

Reference

Detection markers

Checked in this order by detect_provider(). The first match wins.
5 fields
wpengine string
WP Engine. Detected when the is_wpe() function exists and returns true.
Default1 ValuesWP Engine
pressable string
Pressable. Detected when the IS_PRESSABLE constant is defined and truthy.
Default2 ValuesPressable
cloudways string
Cloudways. Detected when IS_CLOUDWAYS is defined and strictly equal to true.
Default3 ValuesCloudways
pantheon string
Pantheon. Detected when the PANTHEON_ENVIRONMENT constant is defined, whatever its value.
Default4 ValuesPantheon
unknown string
No marker matched. Host-specific purging is unavailable; generic layers still work.
Defaultfallback
Flow

Detection to purge

4 relationships
The stored setting is authoritative at runtime, not live detection.

Verify what a site thinks it is

Compare detected and stored provider bash 
wp eval 'echo "detected: " . \Mantle\Helper\HostingProvider::detect_provider() . PHP_EOL;'
wp eval '$s = new \Mantle\Model\Settings(); echo "stored:   " . var_export( $s->get_setting( "hosting_provider" ), true ) . PHP_EOL;'
detected: unknown
stored:   ''

That output is from a local development site, which matches no host marker. A mismatch between the two lines on a production site is the signal to correct the setting.

Cache layers and routes

The module exposes a route per layer, plus host-specific purge routes. All require the convergence_cache module to be enabled.

LayerRouteCapability
Object cache/mantle/v1/cache/clear/objectmantle_clear_cache_object
Page cache/mantle/v1/cache/clear/pagemantle_clear_cache_page
Edge or CDN/mantle/v1/cache/clear/edgemantle_clear_cache_edge
Everything/mantle/v1/cache/clear/allmantle_clear_cache_all
Pressable/mantle/v1/cache/clear/pressable—
WP Engine/mantle/v1/cache/clear/wpengine—
Pantheon/mantle/v1/cache/clear/pantheon—
Cloudflare/mantle/v1/cache/clear/cloudflare—
Request POST /wp-json/mantle/v1/cache/clear/page
HeadersKey: value
Accept application/jsonContent-Type application/jsonX-WP-Nonce REPLACE_WITH_REST_NONCE
Request bodyJSON
{
  "url": "https://example.com/about/"
}
Response 200 OK
BodyJSON
{
  "success": true
}

Providers and cache managers

The module separates two concepts, which is worth knowing when reading the source:

Reference

Providers versus cache managers

Both live under includes/Modules/Convergence_Cache/.
2 fields
Providers string
Describe a platform and what it supports. Implementations: Cloudflare, Cloudways, Pantheon, Pressable, WPEngine, WPRocket. Each implements Cache_Provider_Interface.
DefaultProviders/
Cache managers string
Perform the actual purge. Implementations: Cloudflare_API, Pantheon_Native, Pressable_API, Pressable_Plugin, WPEngine_Native. Each implements Cache_Manager_Interface.
DefaultCache_Managers/

Note that Pressable has two managers — Pressable_API and Pressable_Plugin — because the purge can go through the hosting API or through Pressable's own plugin depending on what is available.

includes/Modules/Convergence_Cache/ File tree
  • Convergence_Cache_Module.php
  • Providers/
    • Cache_Provider_Interface.php
    • Cache_Provider_Abstract.php
    • Cloudflare.php
    • Cloudways.php
    • Pantheon.php
    • Pressable.php
    • WPEngine.php
    • WPRocket.php
  • Cache_Managers/
    • Cache_Manager_Interface.php
    • Cache_Manager_Abstract.php
    • Cloudflare_API.php
    • Pantheon_Native.php
    • Pressable_API.php
    • Pressable_Plugin.php
    • WPEngine_Native.php
  • API/REST/
    • Cache_Purge_REST_Controller.php
    • Module_Settings_REST_Controller.php
  • Helpers/
    • Cache.php
Providers describe platforms; cache managers execute purges.

Cloudflare configuration

Cloudflare is the one provider needing credentials in Mantle's own settings.

Reference

Cloudflare settings keys

Part of the mantle settings option.
5 fields
cloudflare_cache_enabled boolean
Enables the Cloudflare integration.
Defaultfalse Valuestrue, false
cloudflare_api_key string
Cloudflare API key. A credential stored in a WordPress option.
cloudflare_email_address string
Cloudflare account email, paired with the API key.
cloudflare_zone_id string
Zone to purge.
cloudflare_use_alt_account boolean
Use the alternate Cloudflare account credentials.
Defaultfalse Valuestrue, false

Admin bar controls

cache_admin_bar_enabled adds cache controls to the admin bar for users holding the relevant capability, so editors can purge a page while viewing it. Toggle it at /mantle/v1/cache/admin-bar/enable.

Troubleshooting

Guided diagnosis

Cache clearing is not working

Three questions narrow almost every cache-clearing problem.
Question 1
Question 1

Is the convergence_cache module enabled?

See also

Have a question about this page?

Linchpin assistant

Was this helpful?