Statamic Cloudflare Cache Laravel Package

Getting Started

This is a Statamic addon (not a plain Laravel package), so install it in the Statamic site that sits behind Cloudflare.

composer require eminos/statamic-cloudflare-cache
php artisan vendor:publish --tag=statamic-cloudflare-cache-config

Then set credentials in .env — a scoped Cloudflare API token (permission: Zone → Cache Purge, optionally Zone → Zone Read) plus the zone ID:

CLOUDFLARE_API_TOKEN=...
CLOUDFLARE_ZONE_ID=...

First things to read, in order:

1. config/statamic-cloudflare-cache.php — the published config is the real documentation. Look for the enabled/disabled toggle, the event or collection allow-list, and the purge strategy (everything vs. URLs).
2. The addon's service provider / event listener — that's where you'll see exactly which Statamic events trigger a purge.
3. php artisan list filtered for the addon's namespace, to find any manual purge command for smoke-testing.

First use case: make sure the config cache is clear (php artisan config:clear), save and publish a single entry in the CP, then confirm the purge in the Cloudflare dashboard (Caching → Configuration → Purge Cache history, or the audit log). If nothing happens, temporarily set APP_ENV=local aside and check the addon's enabled flag — most failures at this stage are "addon disabled outside production" or a token missing Cache Purge scope.

Implementation Patterns

Event-driven purge as the default. The addon listens to Statamic's save/publish/delete lifecycle and invalidates Cloudflare for you. The normal pattern is: install, configure, forget. Don't call the Cloudflare API yourself in Entry::saved listeners unless you're deliberately bypassing the addon.

Targeted purges via static cache invalidation (v1.5.0+). The new release wires the addon into Statamic's static-cache invalidation so purges can be scoped to the specific URLs that changed instead of nuking the whole zone. Enable it when you have static caching on; the practical pattern is:

• Static cache writes the HTML file → the addon is told which URIs were invalidated → those exact URLs are purged from Cloudflare's edge.
• Keep the URL set small and deterministic; anything you can't resolve to a URL should fall back to a full-zone purge rather than silently doing nothing.

Choose a strategy per environment. Full-zone purge is simplest and most correct; targeted purge is faster to propagate and much gentler on origin. Typical setup: targeted purge in production, full purge (or no purge) in staging, disabled locally.

Queue it. Purges are outbound HTTP calls inside a request that's already doing a save. If your editors save often or you run imports, push the purge onto a queue (QUEUE_CONNECTION=redis) so CP saves stay snappy and you don't hit Cloudflare rate limits.

Programmatic purges. For things Statamic doesn't know about — deploys, asset changes, taxonomy term edits if not covered — wrap the purge in your own deploy hook or Artisan command and run it as the last step of the pipeline. Never purge before the new code is live, or you'll re-cache the old HTML.

Multi-site / multi-domain. Each site resolves to a different hostname; make sure the config maps site → base URL correctly, otherwise you purge example.com/about when the cached copy is example.de/about. Verify per-site after any domain change.

Guard rails. Explicitly disable the addon in local/testing, and skip purges for drafts, revisions, and imports unless you want them. Bulk content migrations are the classic way to burn through your API quota.

Gotchas and Tips

• Token scope is the #1 failure. A Global API Key "works" but is wildly over-privileged; use a scoped token with Cache Purge only. A token with the right scope but the wrong zone ID fails silently-ish — check logs, not the CP.
• Config caching. After editing the config or .env, run php artisan config:clear. In production with config:cache, a changed CLOUDFLARE_ZONE_ID that never takes effect is almost always this.
• Full purge ≠ instant. Propagates globally in seconds to ~30s, but it's per-datacenter; don't assert on it in tests or in a deploy script's health check.
• URL purge requires an exact match — scheme, host, and path, including trailing slash and query string behaviour. Percent-encoded or redirected URLs won't match the cached object, so nothing gets purged and it looks like the addon "didn't work."
• Double caching confusion. With Statamic static caching, Cloudflare, and the browser all caching, a stale page can come from any of the three. Reproduce with curl -I against the origin and against the edge before blaming the addon.
• Rate limits and bursty edits. Saving an entry that touches many relationships can fan out into many purge calls. Batch or queue; Cloudflare will 429 you during content imports.
• Events you didn't expect. Revisions, drafts, and multi-site propagation can all fire saves. If you see purges on every keystroke-ish behaviour in a live-preview setup, narrow the trigger list rather than removing the addon.
• Fallback is your friend. Configure a full purge as the safety net when targeted URL resolution fails — a slightly over-eager purge beats stale content in production.
• Logging. Log the purge payload (URLs, zone, response status) at debug level. Cloudflare's success response is terse, and having the exact URLs on hand turns a 20-minute mystery into a 30-second check.
• Extension point: the addon's purge action is the seam to override if you need custom URL derivation (e.g. purging AMP variants, /api/ JSON endpoints, or sitemap URLs alongside the page).
• Upgrade note: v1.5.0 is additive — the static-cache invalidation integration is opt-in. Upgrading without touching config keeps the existing behaviour, but re-publish/merge the config to see the new keys.