Statamic Cloudflare Cache Laravel Package

Technical Evaluation

Architecture fit

• eminos/statamic-cloudflare-cache is a Statamic addon (Laravel package) that purges Cloudflare edge cache when content changes. v1.5.0 adds an optional integration with Statamic's static-cache invalidation flow so purges can be targeted (per-URL) instead of full-zone.
• Fit is good for the common Statamic topology: Statamic static caching enabled at origin, Cloudflare in front. The new capability aligns the two cache layers rather than treating Cloudflare as a blunt instrument.
• It remains an addon, not framework-level infrastructure — low architectural intrusion, no changes to application code expected.

Integration feasibility

• Standard Composer install plus config/env for API token and zone ID. The v1.5.0 feature is opt-in, so existing 1.4.x installs are unaffected.
• Effective value depends on how Statamic emits static-cache invalidations (per-URL vs. batch) and on Cloudflare plan tier: single-URL purge is broadly available, but purge-by-tag/cache-tag is Enterprise-only, and single-URL purge API calls are capped (commonly 30 URLs per request). Whether this package batches invalidations is the key unknown.

Technical risk

• Plan-tier dependency: targeted purging may degrade to per-URL loops, increasing API call volume and latency.
• Rate limits: Cloudflare's purge API is rate-limited per token/user; high publish frequency on large sites could hit ceilings.
• Semantic mismatch: Statamic static cache invalidation events and Cloudflare's cache key model (query strings, trailing slashes, variants) may not map 1:1, risking partial purges and stale edges.
• Contribution provenance: the feature arrived via a Copilot-authored PR; review depth and test coverage are unverified from release notes alone.
• Fallback behavior: unknown whether failures or unsupported plan tiers fall back to full-zone purge or silently no-op.

Key questions

1. Does the integration batch invalidations into single purge requests, and what is the batch/URL cap handling?
2. Is purging synchronous in the request path or queued? Is a queue driver required?
3. Does it use cache tags (Enterprise) or URL purge, and does it auto-detect plan capability?
4. What happens on API error, token expiry, or when static caching is disabled — fail-open, fail-closed, logged?
5. What are the supported Statamic/Laravel/PHP version constraints, and is 1.4.x → 1.5.0 strictly non-breaking?
6. Are there tests and docs for configuring token scope (Zone.Cache Purge) and zone ID safely?

Integration Approach

Stack fit

• Targets Statamic (Laravel) sites behind Cloudflare with static caching enabled. If static caching is off, v1.5.0's new path is inert and the package behaves as before.
• Fits existing Composer/CI workflows and Statamic's config-publish conventions; no new runtime services.

Migration path

• Minor version bump (1.5.0) with an explicitly optional feature — treat as low-risk upgrade. composer update eminos/statamic-cloudflare-cache, re-publish/merge config if new keys were added, verify env vars.
• No data migration. Rollback is a version pin.

Compatibility

• Verify against our pinned Statamic major, Laravel version, and PHP runtime.
• Confirm Cloudflare plan tier and API token permissions before enabling targeted purges; validate behavior with static caching both on and off.
• Check for conflicts with any existing custom purger, CDN middleware, or Statamic cache listeners.

Sequencing

1. Inventory current cache topology and whether static caching is enabled in each environment.
2. Upgrade in staging with the new integration disabled; confirm parity with 1.4.x behavior.
3. Enable targeted invalidation in staging against a non-production Cloudflare zone; exercise single-URL, multi-URL, and bulk-publish scenarios.
4. Validate edge freshness (curl with cache headers), confirm logging/alerting on purge failures, then roll to production behind the config flag.
5. Keep full-zone purge documented as the manual fallback runbook.

Operational Impact

Maintenance

• Small, single-maintainer package with an added external integration surface (Cloudflare API). Pin the version, watch releases, and budget periodic review of Cloudflare API/plan changes. Copilot-assisted contributions warrant slightly closer changelog review than a mature maintainer-only repo.

Support

• Support burden is mostly configuration and credential issues (token scope, zone ID) plus “why is stale content served” investigations. Requires an internal runbook covering manual purge fallback and token rotation. Upstream docs may lag the new feature.

Scaling

• Purge volume scales with publish frequency × affected URL count. Large content operations (bulk imports, taxonomy changes) can generate many invalidations; without batching/queueing this risks Cloudflare rate limits and slow editorial requests. Recommend queue-backed purging and debounce/coalescing for bulk operations.

Failure modes

• Purge API failure or expired token → stale content at the edge with no user-visible error.
• Plan-tier mismatch (tags unavailable) → degraded or failed targeted purges.
• Wrong zone ID → purges against the wrong zone.
• Partial purges from URL/variant mismatch → inconsistent content across edge nodes.
• Cloudflare outage or throttling → delayed invalidation; origin remains correct but users see stale pages.
• Each of these needs explicit logging/alerting; silent no-ops are the primary operational hazard.

Ramp-up

• Low for Laravel/Statamic developers: config + env + one behavior toggle. Estimate ~1–2 engineering days for staging validation and runbook authoring, plus a small ongoing on-call note. No specialist Cloudflare knowledge required beyond token scoping and purge limits.