aceextension/module-cloudflare-cache

Cloudflare cache purge integration for Magento 2

dev-main 2026-03-19 10:56 UTC

Requires

• aceextension/ace-core: ^1.0

OSL-3.0

README

Cloudflare cache purge integration for Magento 2. Automatically triggers a Cloudflare purge when Magento cache is cleaned or flushed (via Admin or CLI).

Features

• Purges Cloudflare cache whenever Magento cache is:
  • Cleaned (cache:clean / Admin “Flush Magento Cache”)
  • Flushed (cache:flush / Admin “Flush Cache Storage”)
• Admin configuration for:
  • Enable/Disable integration
  • Cloudflare Zone ID
  • API Token (stored encrypted)
  • Purge Everything toggle
• Depends on Aceextension_Core for shared helpers.

Requirements

• Magento 2.4.x
• PHP 8.1 or newer
• A Cloudflare API Token with permission to “Cache Purge” for the target Zone

Installation

1. Place the module in app/code/Aceextension/CloudflareCache.

2. Run the usual setup commands:

   php bin/magento setup:upgrade
   php bin/magento cache:flush

3. (Optional) If you use Composer for local modules, ensure autoload is refreshed:

   composer dump-autoload

Configuration

• Navigate to: Stores → Configuration → Ace Extensions → Cloudflare Cache
• Settings:
  • Enable Integration: Yes/No
  • Zone ID: Your Cloudflare Zone ID (found in Cloudflare dashboard)
  • API Token: A token with purge permission for the Zone (stored encrypted)
  • Purge Everything: Yes/No

Save configuration and clear Magento cache after changes.

How It Works

• The module attaches a plugin to Magento’s Cache Manager:
  • afterClean and afterFlush automatically call the Cloudflare API.
• API endpoint used:
  • POST https://api.cloudflare.com/client/v4/zones/{ZONE_ID}/purge_cache
  • Authorization: Bearer {API_TOKEN}
• Payload:
  • When “Purge Everything” is enabled, {"purge_everything": true} is sent.
  • (Future extension can add URL/Host/Tag-specific payloads.)

Testing

1. Configure Zone ID and API Token in Admin.

2. Run:

   php bin/magento cache:clean

3. Verify in Cloudflare dashboard that a purge occurred, or check Magento logs for entries related to Cloudflare purge status.

Security Notes

• The API Token is stored using Magento’s encrypted backend model and is never logged.
• If a purge fails, only status/error messages are logged without secrets.
• Use a least-privilege API token scoped to the required Zone and “Cache Purge” permission.

Troubleshooting

• No purge happens:
  • Ensure “Enable Integration” is set to Yes.
  • Verify Zone ID and API Token.
  • Check that cache clean/flush actually runs (Admin or CLI).
• API errors in logs:
  • Confirm the token has the correct permissions and the Zone ID is correct.
  • Check outbound connectivity to api.cloudflare.com from your environment.

Extending

• Purge by URLs/Hosts/Cache-Tags:
  • Add new config fields for modes and a UI for entering URLs/hosts.
  • Update Model/Client.php to build appropriate payloads (files, hosts, or tags).
• Selective triggers:
  • Narrow the plugin logic to specific cache types by inspecting $types in afterClean.
• CLI command:
  • Add a Magento CLI command to manually purge Cloudflare on demand.

Module Structure

• etc/module.xml – module declaration, depends on Aceextension_Core
• etc/adminhtml/system.xml – Admin configuration fields
• etc/acl.xml – Admin ACL for configuration
• etc/di.xml – Plugin registration for Cache Manager
• Helper/Data.php – Configuration access (extends Core helper)
• Model/Client.php – Cloudflare API client (Curl-based)
• Plugin/CacheManagerPlugin.php – Hooks into cache clean/flush

Uninstall

1. Disable the module and remove its directory:

   php bin/magento module:disable Aceextension_CloudflareCache
   rm -rf app/code/Aceextension/CloudflareCache
   php bin/magento setup:upgrade
   php bin/magento cache:flush