cloudflare_purge

The Cloudflare Purge module provides a secure and comprehensive way to purge Cloudflare cache directly from your Drupal site. It uses Drupal's built-in Guzzle HTTP client and supports both modern Bearer Token and legacy API Key authentication methods.

This module replicates the functionality of Cloudflare's Purge Cache API using Drupal's secure HTTP client:

curl -X POST "https://api.cloudflare.com/client/v4/zones/YOUR_ZONE_ID/purge_cache" \
 -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
 -H "Content-Type: application/json" \
 --data '{"purge_everything":true}'

Works with Cloudflare's free tier and provides both web UI and Drush command-line interfaces for cache management.

Key Features

• Purge Everything – Clear all cached content with confirmation dialog
• Purge by URL – Clear one or more specific URLs (up to 30 per request)
• Purge by Cache Tag – Clear content by cache tags (all plans)
• Purge by Prefix – Clear all content under URL prefixes (all plans)
• Purge by Hostname – Clear all content for specific hostnames (all plans)
• Automatic Cache Tag Purging – Automatically purge Cloudflare when Drupal cache tags are invalidated
• Queue-Based Processing – Queue purge requests for batch processing during cron
• Purge History – View recent purge operations from the admin UI
• Bearer Token Authentication – Modern, secure API authentication with granular permissions (recommended)
• Legacy API Key Authentication – Email + API Key authentication for backward compatibility
• Flexible Storage Options – Choose between plain text or Key module for credential storage
• Key Module Integration – Optional integration for secure credential storage outside the database
• Settings.php Override – Store credentials securely outside the database for production environments
• Smart Configuration Detection – Automatically detects and preserves existing credentials
• Drush Commands – Full command-line support for all purge operations
• Credential Validation – Forms disabled until credentials are configured
• CSRF Protection – Built-in security for all purge operations
• Permissions System – Granular access control for different user roles
• Responsive UI – Modern two-column layout with Cloudflare branding
• Free Tier Compatible – Works with Cloudflare's free plan

Latest Version Highlights

Comprehensive purge operations with Drupal 10.3+ and 11 compatibility!

• Drupal 10.3+ and 11 compatible
• PHP 8.1+ with strict typing throughout
• All Cloudflare purge methods – URL, Tag, Prefix, Hostname, Everything
• Automatic cache tag integration with Drupal's cache system
• Queue support for high-traffic sites
• Full dependency injection following Drupal coding standards
• Modern authentication system with Bearer Token as default
• Flexible storage methods – Plain text or Key module integration
• Enhanced security with three-tier credential resolution
• Drush 13 commands with PHP 8 attributes for all operations
• Improved error handling and logging
• Configuration schema for proper validation
• Clean uninstall removes all configuration

Purge Operations

Operation Description Plan Required Purge Everything Clear entire Cloudflare cache for your zone Free Purge by URL Clear 1-30 specific URLs per request Free Purge by Cache Tag Clear content by cache tags (up to 30 tags) All plans* Purge by Prefix Clear all content under URL prefixes All plans* Purge by Hostname Clear all content for specific hostnames All plans*

*As of April 2025, Cloudflare made all purge methods available on all plans. Free tier has stricter rate limits (5 requests/minute). See Cloudflare's documentation for current limits.

Typical Use Cases

• Your hosting provider enables Cloudflare through a Certified Partner but doesn't provide Drupal integration
• You need a lightweight cache purging solution without additional dependencies
• You want command-line control via Drush for automated deployments
• You can't use the full Purge module ecosystem
• You need to clear cache for specific URLs after content updates
• You want automatic cache invalidation when Drupal content changes
• You require enterprise-level credential security with external key management

Relationship to the Cloudflare Module

The Cloudflare Purge module is an alternative way to talk to Cloudflare from Drupal. The Cloudflare module (and its Cloudflare Purger submodule) integrate with the Purge ecosystem and the Cloudflare PHP SDK, while this module focuses only on cache purging using Drupal core’s HTTP client and its own UI/Drush commands. If you are already happy with the Cloudflare module and Purge, you can keep using them; if you just need a simple, standalone way to trigger Cloudflare cache purges from Drupal, this module may be a good fit.

Requirements

• Drupal: 10.3 or higher, or Drupal 11
• PHP: 8.1 or higher
• Cloudflare Account: Free tier or higher
• Cloudflare Zone ID: Found in your domain's overview page
• Authentication (choose one):
  • Bearer Token with Cache Purge permission (recommended)
  • Global API Key + Email address (legacy)
• Optional:
  • Key module for enhanced credential security
  • Higher rate limits on paid plans for tag, prefix, and hostname purging

Installation

Install via Composer (recommended):

composer require drupal/cloudflare_purge
drush en cloudflare_purge

Or install as you would any contributed Drupal module. Visit the Drupal.org module installation documentation for more information.

Optional: For enhanced security, install the Key module:

composer require drupal/key
drush en key

Configuration

Quick Start: Via Admin Interface

Navigate to Configuration → Cloudflare Purge

(/admin/config/cloudflare-purge/credentials)

Configuration Steps:

1. Choose Authentication Method:
   • Bearer Token (recommended) – Modern API Token with granular permissions
   • Legacy API Key/Email – Email + Global API Key for older setups
2. Choose Storage Method:
   • Plain text input – Quick setup, credentials stored in database
   • Secure key input – Use Key module for enhanced security (requires Key module)
3. Enter Credentials:
   • Zone ID (required for all methods)
   • Bearer Token OR Email + API Key (based on authentication choice)
4. Save configuration

Auto-Purge Settings (Optional)

Navigate to Configuration → Cloudflare Purge → Auto-Purge Settings

(/admin/config/cloudflare-purge/settings)

Configure automatic cache purging when Drupal cache tags are invalidated:

• Enable automatic purging – Purge Cloudflare when content changes
• Entity types – Select which entities trigger automatic purges
• Queue processing – Use queue for high-traffic sites
• Tag prefix – Add prefix for multi-site setups sharing a zone
• Detailed logging – Enable for debugging

Note: Free tier has rate limits of 5 requests/minute for tag-based purging. Consider using queue processing for high-traffic sites.

Creating Cloudflare Credentials

For Bearer Token (Recommended):

1. Log into your Cloudflare dashboard
2. Go to Profile → API Tokens → Create Token
3. Use "Edit zone DNS" template or create custom token
4. Set permission: Zone → Cache Purge → Purge
5. Select your zone(s)
6. Create and copy the token (shown only once!)

Finding Zone ID:

• Log into Cloudflare dashboard
• Select your domain
• Zone ID is shown in the right sidebar of the overview page

Enhanced Security: Key Module Integration

The Key module allows you to store credentials outside of the database using secure providers:

Available Key Providers:

• Configuration – Store in Drupal config (encrypted if using CMI encryption)
• File – Store credentials in a file outside the webroot
• Environment – Use environment variables
• Lockr – Cloud-based key management service
• HashiCorp Vault – Enterprise key management
• And many more via Key module plugins

Setup with Key Module:

1. Install the Key module: composer require drupal/key && drush en key
2. Navigate to Configuration → System → Keys (/admin/config/system/keys)
3. Create keys for:
   • Zone ID
   • Bearer Token (or Email + API Key for legacy)
4. Go to Cloudflare Purge configuration
5. Select "Secure key input" as storage method
6. Select your keys from the dropdowns
7. Save configuration

Benefits of Key Module:

• ✓ Credentials never stored in the database
• ✓ Credentials excluded from configuration exports
• ✓ Support for enterprise key management systems
• ✓ Environment-specific keys (dev/staging/production)
• ✓ Centralized credential management across multiple modules
• ✓ Audit trail and access control (with compatible providers)

Production Deployment: settings.php Override

In production environments, store credentials in settings.php:

Important: You must provide a complete set of credentials:

• Bearer Token method: zone_id + bearer_token
• Legacy method: zone_id + email + authorization

Bearer Token Example (Recommended):

$settings['cloudflare_purge_credentials'] = [
  'zone_id' => 'your-zone-id-here',
  'bearer_token' => 'your-bearer-token-here',
];

Legacy API Key Example:

$settings['cloudflare_purge_credentials'] = [
  'zone_id' => 'your-zone-id-here',
  'email' => '[email protected]',
  'authorization' => 'your-global-api-key-here',
];

Environment Variables Example:

// Load from environment
if (isset($_ENV['CLOUDFLARE_ZONE_ID'])) {
  $settings['cloudflare_purge_credentials'] = [
    'zone_id' => $_ENV['CLOUDFLARE_ZONE_ID'],
    'bearer_token' => $_ENV['CLOUDFLARE_BEARER_TOKEN'],
  ];
}

Benefits of settings.php:

• ✓ Credentials never stored in database
• ✓ Not exported with configuration
• ✓ Perfect for multi-environment workflows (dev/staging/production)
• ✓ Highest security level
• ✓ Configuration form automatically disabled when complete credentials detected

Credential Resolution Priority

The module uses a three-tier system for resolving credentials:

1. settings.php – Highest priority, always wins (production recommended)
2. Key module – If installed and configured (enhanced security)
3. Plain text config – Database storage (quick setup, backward compatibility)

Usage

Web Interface

Navigate to Configuration → Cloudflare Purge:

• Credentials: /admin/config/cloudflare-purge/credentials
• Auto-Purge Settings: /admin/config/cloudflare-purge/settings
• Purge by URL: /admin/config/cloudflare-purge/purge-url
• Purge by Cache Tag: /admin/config/cloudflare-purge/purge-tag
• Purge by Prefix: /admin/config/cloudflare-purge/purge-prefix
• Purge by Hostname: /admin/config/cloudflare-purge/purge-hostname
• Purge Everything: /admin/config/cloudflare-purge/purge-everything
• Purge History: /admin/config/cloudflare-purge/history

Note: Purge forms are disabled until credentials are configured. A warning message with a link to the credentials page will be displayed.

Drush Commands

# Purge all cache
drush cloudflare:purge-all
drush cf-purge-all    # alias
drush cfpa            # short alias

# Purge specific URL(s)
drush cloudflare:purge-url https://example.com/page
drush cf-purge-url https://example.com/a https://example.com/b
drush cfpu "https://example.com/a,https://example.com/b"

# Purge by cache tags (all plans)
drush cloudflare:purge-tags node-123 taxonomy-term-45
drush cf-purge-tags "product-1,product-2,product-3"
drush cfpt node-123

# Purge by prefix (all plans)
drush cloudflare:purge-prefixes https://example.com/blog/
drush cf-purge-prefixes "https://example.com/products/,https://example.com/images/"
drush cfpp https://example.com/blog/

# Purge by hostname (all plans)
drush cloudflare:purge-hostnames www.example.com cdn.example.com
drush cf-purge-hosts "images.example.com,static.example.com"
drush cfph cdn.example.com

# Check configuration status
drush cloudflare:status
drush cf-status
drush cfs

Example output:

$ drush cloudflare:purge-url https://example.com/node/1
 [success] Successfully purged 1 of 1 URL(s).

$ drush cloudflare:status
 [success] Cloudflare credentials are configured.

Permissions

Configure at People → Permissions:

• Administer Cloudflare Purge (administer cloudflare purge) – Configure credentials and settings
• Perform manual Cloudflare purge operations (cloudflare purge) – Execute purge by URL, tag, prefix, hostname
• Purge entire Cloudflare cache (cloudflare purge everything) – Clear all cached content
• View Cloudflare purge history (view cloudflare purge history) – View recent purge operations

Cloudflare API Limits

Limit Type Value URLs per request 30 Cache tags per request 30 Prefixes per request 30 Hostnames per request 30 API calls (Free tier) 1,000/day

Rate Limits by Plan (Tag/Prefix/Hostname/Purge Everything)

Plan Requests Bucket Size Max Ops/Request Free 5/minute 25 100 Pro 5/second 25 100 Business 10/second 50 100 Enterprise 50/second 500 100

The module automatically batches larger requests when using Drush commands.

Important: Rate limits are subject to change. For the latest information, see Cloudflare's official documentation. (Last verified: January 2026)

Security

• ✓ CSRF token protection on all purge routes
• ✓ Permission-based access control
• ✓ Confirmation form for destructive "Purge Everything" operation
• ✓ Forms disabled until credentials configured
• ✓ Guzzle HTTP client for secure API communication
• ✓ Three-tier credential resolution system
• ✓ Optional Key module integration for external credential management
• ✓ settings.php override keeps credentials out of the database
• ✓ Bearer Token support with limited-scope permissions
• ✓ Complete input validation on all forms
• ✓ Comprehensive error logging to Drupal watchdog
• ✓ Configuration deleted on module uninstall
• ✓ Automatic cleanup when switching authentication/storage methods
• ✓ PHP 8.1+ strict typing throughout
• ✓ Full dependency injection following Drupal standards

Troubleshooting

Check Drupal Logs

If purging fails, check Reports → Recent log messages for entries from the cloudflare_purge channel.

Common Issues

"Cloudflare credentials are not configured"

• Verify Zone ID is entered
• Verify authentication credentials (Bearer Token OR Email + API Key) are entered
• If using settings.php, ensure you have a complete set of credentials
• Clear cache after configuration changes

Form submit button is disabled

• Credentials are not configured
• Configure credentials at /admin/config/cloudflare-purge/credentials
• Button will be enabled once valid credentials are saved

Incomplete credentials warning

• settings.php has partial credentials but not a complete set
• Either complete the credentials in settings.php or remove them entirely
• Form remains enabled to allow configuration until settings.php is complete

Key module "Secure key input" not showing

• Install Key module: composer require drupal/key && drush en key
• Clear cache: drush cr
• Refresh configuration form

API call fails

• Check Bearer Token has Cache Purge permission in Cloudflare dashboard
• Verify Zone ID is correct (32-character hexadecimal string)
• Check for rate limit errors (Free: 1,000 API calls per day)
• Review Drupal logs for detailed error messages

Tag/Prefix/Hostname purging fails

• Check you haven't exceeded rate limits (Free: 5 requests/minute)
• Verify the format is correct (tags: no spaces, prefixes: full URLs, hostnames: no protocol)

Auto-purge not working

• Verify auto-purge is enabled at /admin/config/cloudflare-purge/settings
• Check entity types are selected
• Free tier has rate limits (5 requests/minute) - use queue processing
• If using queue, ensure cron is running: drush cron

Resources

• Cloudflare Purge Availability & Limits – Current rate limits by plan
• Cloudflare Purge Cache API Documentation
• Getting Started with Cloudflare API
• Cache Purge Best Practices
• Using Cloudflare and Drupal: Five Recommended Steps
• Key Module – For enhanced credential security
• Key Module Documentation

Legal Disclaimer

This module has not been built, maintained, or supported by Cloudflare, Inc. This is an independent open-source project with no official association with Cloudflare, Inc. The module uses Cloudflare's public API under their terms of service.

Cloudflare® is a registered trademark of Cloudflare, Inc.

back to top ☝️

Developed & Designed By: Alaa Haddad

A Personal Thank You for Your Support

Every project you see here, including this one, reflects countless hours of work driven by my passion for making Drupal better for everyone. Your support truly makes a difference, and there are a few simple ways you can help these projects grow and reach others who might benefit:

• Use & Share Feedback: Have you found this project (or any of my other work) helpful? Let me know what worked well or how it could be improved. Real user input drives better tools for the entire community.
• Click "Like" on Drupal.org: It may seem small, but liking this project on Drupal.org helps others discover and trust these tools.
• Spread the Word: Share these projects on social media, Slack groups, or anywhere Drupal folks connect. Your word of mouth helps these tools find the people who need them.
• Explore More of My Work: Check out my other projects on Drupal.org to see what else might support your workflow or inspire your next build.

W3CSS Theme (d8w3css) - Solo - W3CSS Paragraphs - Paragraphs Bundles - Amun - Amunet - Anhur - Acquia Purge Varnish - Cloudflare Purge - Reference Blocked Users - Solo Copy Blocks - Solo Utilities - PB Import - VVJA - Accordion - VVJC - 3D Carousel - VVJB - Basic Carousel - VVJF - 3D FlipBox - VVJH - Hero - VVJL - Lightbox - VVJP - Parallax - VVJR - Reveal - VVJS - Slideshow - VVJT - Tabs - Module Matrix - Selectify - Utilikit

If you have any questions, ideas, or feedback about my Drupal.org projects, I’d love to hear from you! To keep things open and helpful for the entire community, I encourage you to post directly in the project's issue queue on Drupal.org. This way, your questions and the answers can benefit others who may have the same needs.

At the end of the day, my goal is to make Drupal easier and more enjoyable for everyone, especially small businesses and site builders who want to create professional sites without extra hassle. Together, we can build something even better. Thank you for your support, and for being part of this journey!