Powerful all-in-one Cloudflare cache solution for WordPress: edge HTML caching, automatic purging, AJAX admin controls, API token support, and comprehensive logging.
Explore the docs »
View Demo
·
Report Bug
·
Request Feature
Table of Contents
Cloudflare Smart Cache is a WordPress plugin that integrates Cloudflare's edge caching with automatic cache purging. It serves HTML pages from Cloudflare's edge for non-logged-in visitors, automatically purges cache on content changes, and provides a full AJAX admin interface with zero page reloads.
Key features:
- Edge HTML Caching — Serve HTML pages from Cloudflare's edge cache for non-logged-in visitors with configurable TTL (stale-while-revalidate, stale-if-error)
- Automatic Cache Purging — Purge Cloudflare cache when posts, categories, terms, menus, or themes change
- Selective Purge by Post Type — Choose which post types trigger cache purging in Settings
- Cache Hit Rate Alert — Admin warning when hit rate stays below 30% for 3+ consecutive checks
- Scheduled Full Purge — WP-Cron driven daily or weekly automatic full cache clearance
- AJAX Admin Interface — All operations (save, purge, refresh, auto-config) use inline vanilla JS with zero page reloads
- Real-Time Activity Log — Live log viewer auto-refreshes every 5 seconds via AJAX polling, color-coded by severity
- Auto-Configuration Wizard — One-click setup of Page Rules (Cache Everything), DNS Proxy (orange cloud), and zone settings, with backup/rollback
- Security Headers — X-Content-Type-Options, X-Frame-Options, HSTS, X-XSS-Protection, Referrer-Policy
- Cache Statistics — Track hits, misses, hit rate, bypass reasons, and cached URLs
- Rate Limiting — Sliding-window governor with exponential back-off and adaptive limiting on 429 responses
- API Token Authentication — Secure Bearer token for Cloudflare API access (supports Profile API Tokens)
- Activity Log — View recent 50 log entries from plugin operations
- Developer Hooks — 7 documented actions and filters for custom integration
- Real-time activity log — AJAX auto-refresh every 5 seconds via
fetch_logsendpoint, color-coded rows by severity - Comprehensive logging — All user actions now logged: settings save, zone refresh, auto-config (backup/apply/rollback), hit rate alert dismiss, purge operations
- VitePress documentation site — Deployed to Cloudflare Pages at https://cf-smart-cache.pages.dev
- Bug fix: Refresh Zone List button no longer disappears after click (button moved outside
innerHTML-replaced container) - Complete code audit for
innerHTMLDOM patterns — all 6 usages verified safe - Cleanup: removed unused params/variables in zone refresh flow
- Complete architecture rewrite: monolithic
core.php(1499 lines) +admin.php(913 lines) split into 6 focused OOP classes - All operations use inline vanilla JS with
onclickhandlers — zero dependency on jQuery or external JS files - Bug fixes: activation "headers already sent", plugin search infinite loading, zone list pagination (
per_page=50) - Backward compatible: all 54 existing function names preserved as thin wrappers
- Minimalist admin UI with tab switching, AJAX settings save, AJAX purge, inline notifications
- Selective purge by post type — Settings checkbox group to filter which post types trigger purge
- Cache hit rate alert — Admin warning notice when hit rate < 30% for 3+ consecutive checks (50+ total requests minimum)
- Scheduled full-site purge — Daily or Weekly WP-Cron option in Settings
- PHPUnit test framework — 10 tests, 22 assertions across 3 test classes
- Developer hooks documentation —
docs/developer-hooks.mdwith all actions, filters, class reference, and JS API
To use Cloudflare Smart Cache, you need a WordPress site and a Cloudflare account with a Profile API Token.
- WordPress 5.0 or higher
- PHP 7.4 or higher
- Cloudflare account with domain(s) added
- Cloudflare Profile API Token (not Account API Token)
- Download or clone the plugin:
git clone https://github.com/LoveDoLove/cloudflare-smart-cache.git
- Upload the
cf-smart-cachefolder to your WordPresswp-content/plugins/directory. - Activate the plugin in the WordPress admin dashboard.
- Go to Settings > CF Smart Cache and enter your Cloudflare API token and select your zone.
- Save settings (AJAX, no page reload).
- Go to Cloudflare Dashboard > My Profile > API Tokens
- Click Create Token and choose a custom token
- Add the following permissions:
- Zone > Zone > Read (to list zones)
- Zone > Cache Purge > Edit (to purge cache)
- Zone > Page Rules > Edit (to apply cache rules via Auto-Config)
- Zone > Page Rules > Read (to check existing rules)
- Use a Profile API Token (not an Account API Token)
- Copy the token and paste it in the plugin settings
After activation and configuration:
- The plugin automatically purges Cloudflare cache when posts, categories, or terms are updated or deleted
- Use the admin page (Settings > CF Smart Cache) with four tabs:
- View cache statistics: total requests, hits, misses, hit rate (color-coded)
- View bypass reasons breakdown
- View recent cached URLs
- Click Purge All Cache or Purge Homepage (AJAX, no reload)
- Configure Cloudflare API Token and select Zone
- Access the zone list via AJAX with inline Refresh button
- Configure TTL values for different content types
- Configure rate limiting parameters
- Purge on Post Types — checkboxes to select which post types trigger automatic cache purge
- Scheduled Full Purge — select Disabled, Daily, or Weekly
- View Cache Hit Rate Alert when hit rate drops below 30%
- View current configuration status (Page Rule, Origin Cache Control, DNS Proxy, Backup)
- Page Rule status shows detailed error messages when API permissions are missing
- Auto-Configuration Wizard: Apply Page Rule + DNS Proxy settings with one click
- Backup Now: Save current Cloudflare configuration (up to 3 slots)
- Rollback: Restore a previous configuration backup
- View the last 50 log entries from plugin operations
- Auto-refreshes every 5 seconds via AJAX — no manual page reload needed
- Color-coded rows: info (normal), warning (yellow), error (red)
- Quick access to the plugin settings page
- Quick Purge All Cache button
The plugin provides the following hooks for custom integration:
| Hook | Type | Description |
|---|---|---|
cf_smart_cache_ttl |
Filter | Modify TTL values for cached pages |
cf_smart_cache_purge_urls |
Filter | Filter URLs to purge on content changes |
cf_smart_cache_post_purge_urls |
Filter | Filter related URLs based on post relationships |
cf_smart_cache_bypass_cookies |
Filter | Filter cookies that trigger cache bypass |
cf_smart_cache_supported_post_types |
Filter | Filter which post types support cache purge |
cf_smart_cache_after_settings_save |
Action | After settings are saved |
cf_smart_cache_after_purge_all |
Action | After full cache purge |
See docs/developer-hooks.md for complete reference with parameters and examples.
Full documentation is available at https://cf-smart-cache.pages.dev, covering features, installation, usage, and FAQ.
composer install
vendor/bin/phpunit- Edge HTML caching with dynamic TTL (stale-while-revalidate, stale-if-error)
- Security headers (X-Content-Type-Options, HSTS, CSP, etc.)
- Automatic cache purge on content changes (posts, terms, menus, themes)
- Purge URL generation with hash-based caching (wp_cache + post_meta)
- API rate limiting with sliding window and exponential backoff
- Selective purge by post type
- Cache hit rate alert (admin notice when rate < 30%)
- Scheduled full-site purge (daily/weekly WP-Cron)
- PHPUnit test framework (10 tests, 22 assertions)
- Developer hooks documentation
- Static file caching extensions
- Cache warming on content publish
- Multi-zone support
- Webhook-based purge triggers
See the open issues for a full list of proposed features and known issues.
Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.
If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement".
Don't forget to give the project a star! Thanks again!
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/AmazingFeature) - Commit your Changes (
git commit -m 'Add some AmazingFeature') - Push to the Branch (
git push origin feature/AmazingFeature) - Open a Pull Request
Distributed under the MIT License. See LICENSE for more information.
LoveDoLove - @LoveDoLove
Project Link: https://github.com/LoveDoLove/cloudflare-smart-cache