OCMLABS/MODULE-CLOUDFLARE · PURGING

Purging Cloudflare by cache tag, URL or prefix when Magento invalidates, through a queue that respects Cloudflare's rate limits

What triggers a purge

The module listens to the same events Magento’s own cache invalidation uses, so anything that cleans the full page cache also reaches Cloudflare:

Magento action	What is purged
Saving a product, category, CMS page or block, or any `clean_cache_by_tags` event	The tags Magento cleaned, for example `cat_p_12` or `cms_p_3`
A reindex that cleans cache (`clean_cache_after_reindex`)	The tags the indexer invalidated
Flush Magento Cache or Flush Cache Storage in the admin, or `bin/magento cache:flush`	Everything, when Purge Everything on Full Page Cache Clean is on
Refreshing the Page Cache type, or `bin/magento cache:clean full_page`	Everything, when Purge Everything on Full Page Cache Clean is on
Turning Cloudflare development mode off from the dashboard	Everything, optional checkbox
Quick purge on the dashboard, or the `ocmlabs:cloudflare:purge` command	Whatever you listed

A tag purge sends exactly the tags Magento cleaned. The store_* and website_* tags that every page carries are left out, because purging them would wipe the whole site on every save.

Purge modes

By cache tag (recommended). The tags are sent to Cloudflare’s purge-by-tag endpoint. Cloudflare removes every cached page whose Cache-Tag header carried one of them. Available on every plan.

By URL. For setups where something between Magento and Cloudflare strips the Cache-Tag header. Product tags (cat_p_<id>) resolve to the product URL on each store of the website, plus the URLs of configurable parents. Category tags (cat_c_<id>) resolve to the category URL and its paginated pages. CMS page tags (cms_p_<id>) resolve to the page URL. A tag that resolves to more than Max URLs per Tag (500 by default), or a tag with no URL mapping such as cat_c_p_*, purges everything instead. The aggregate is capped at 5000 URLs per run.

Purge everything. Every invalidation purges the whole zone. Simple, but the edge is cold after every product save.

The queue

With Purge Asynchronously on (the default), observers do not call Cloudflare. They publish a message to the ocmlabs.cloudflare.purge queue on Magento’s built-in db connection, and the ocmlabsCloudflarePurge consumer does the work. Saving a product never waits on the Cloudflare API, and an API outage never breaks an admin save.

The consumer is a batch consumer. Everything that has queued up since the last run is merged into one pass: duplicate tags are dropped, tags for the same zone are grouped, and each group is sent in chunks of 100 items, which is Cloudflare’s limit per request. A catalog import that cleaned ten thousand tags becomes a hundred API calls, not ten thousand.

If more than 20 messages are waiting for one zone, the consumer collapses the backlog into a single purge-everything request, logged with the trigger backlog_collapse. One cold cache is cheaper than hours of queued tag purges.

The consumer must run. Magento’s cron starts it through cron_consumers_runner, or you run it under a supervisor; see the Installation page. The “Purge queue consumer” health check compares the time of the last cache clean event with the time of the last completed purge and warns when the queue is falling behind.

NOTE /

With Purge Asynchronously off, the purge runs inside the request that triggered it. A slow or unreachable Cloudflare API then delays that admin save. Keep it on unless you have a reason not to.

Rate limiting per plan

Cloudflare limits purge requests per zone, and the limit depends on the plan. The module keeps a local token bucket per Cloudflare account, sized to the plan it detected, and spends one token per 100-item request:

Plan	Purge requests allowed	Burst
Free	5 per minute	25
Pro	5 per second	25
Business	10 per second	50
Enterprise	50 per second	500

When the bucket is empty the consumer stops, re-queues only the items it has not sent yet, and tries again on its next run. When Cloudflare answers 429 Too Many Requests the module blocks the bucket for the Retry-After period it was given. Tags wait in the queue; they are never dropped. On a Free zone a large import may take a few minutes to purge fully, and the log shows each batch as it goes.

The purge log

Every purge is recorded under System > Cloudflare > Purge Log: when it ran, the zone and website, the mode (tag, URL, prefix or everything), what triggered it, how many items it carried, the status (success, failed or queued), how long the API call took and Cloudflare’s request ID for support tickets. Open a row to see the items themselves and, for a failed purge, the error Cloudflare returned with the token redacted. Failed and queued rows have a Retry action.

Rows older than 30 days are deleted by a nightly cron.

Quick purge from the dashboard

The Overview tab has a quick purge panel for the selected website: paste cache tags, URLs or prefixes (host plus path, for example www.example.com/catalog) one per line, or purge everything. These purges skip the queue and run immediately, so you see the result straight away. They need the OCMLabs_Cloudflare::purge ACL resource.

The same is available from the command line:

bin/magento ocmlabs:cloudflare:purge --tag=cat_p_12 --tag=cat_c_3
bin/magento ocmlabs:cloudflare:purge --url=https://www.example.com/some-product.html
bin/magento ocmlabs:cloudflare:purge --prefix=www.example.com/catalog
bin/magento ocmlabs:cloudflare:purge --all

In a deploy pipeline, purge after static content is deployed:

bin/magento setup:static-content:deploy
bin/magento ocmlabs:cloudflare:purge --all

Every option is documented on the CLI Reference page.