Acquia Purge Varnish - API V2

Acquia Purge Varnish provides Varnish cache management for Acquia Cloud Platform directly from your Drupal site. Built with modern Drupal standards and using Acquia's Cloud API v2, this module enables administrators to clear Varnish caches through an intuitive web interface or comprehensive Drush commands.

Key Features

• Web UI & Drush Support – Manage cache purging via admin interface or powerful CLI commands
• Acquia Cloud API v2 – Built with the latest API version as recommended by Acquia
• Flexible Domain Purging – Clear cache for current domain only or all domains in the environment
• OAuth2 Authentication – Secure API communication using industry-standard authentication
• Environment Auto-Detection – Automatically detects and works with your current Acquia environment
• Settings.php Override – Secure credential management for production environments
• Comprehensive Logging – Optional request logging for debugging and monitoring
• Permission-Based Access – Role-based access control for cache management

Security

Security is built into every aspect of this module:

• CSRF Protection – All routes protected with Drupal's CSRF token system
• OAuth2 Authentication – Secure API authentication flow
• Guzzle HTTP Client – Uses Drupal core's secure HTTP client (more info)
• Strict Type Safety – PHP strict types throughout for runtime safety
• Credential Protection – API credentials never exposed in logs or UI (unless explicitly enabled)
• Clean Uninstall – All configuration and credentials removed on module uninstall

Drush Commands

Complete CLI integration with Drush:

• drush apv-purge – Purge Varnish cache with optional domain targeting
• drush apv-status – Display environment and configuration status
• drush apv-domains – List all domains (supports JSON/YAML output)
• drush apv-test – Test API credentials and connectivity
• drush apv-config – Configure module settings via CLI

Requirements

• Drupal: ^10 || ^11 || ^12 (declared in acquia_purge_varnish.info.yml and composer.json; Drupal 12 support arrives in 3.0.2)
• Platform: Acquia Cloud Platform (dev, stage, or prod environment)
• Credentials: Acquia Cloud API Key and API Secret with cache-clearing permissions
• Drush: 13.x (optional, for CLI commands)

Configuration

Option 1: Web UI

Navigate to Configuration → Acquia Purge Varnish → Settings

/admin/config/acquia-purge/settings

Option 2: Drush Commands

drush apv-config --api-key="YOUR_KEY" --api-secret="YOUR_SECRET"
drush apv-config --domain=all

Option 3: Settings.php Override (Recommended for Production)

$settings['acquia_purge_varnish_credentials'] = [
  'api_key' => 'your-acquia-api-key',
  'api_secret' => 'your-acquia-api-secret',
  'application_name' => 'your-app-name', // Optional - auto-detects from AH_SITE_GROUP
];

When using settings.php override, form fields are automatically disabled with an override notice.

Getting API Credentials

1. Log in to Acquia Cloud Platform
2. Navigate to Profile → API Tokens
3. Click "Create Token" and provide a descriptive label
4. Copy the API Key and API Secret immediately (Secret shown only once)
5. Ensure your Acquia account has permissions to clear caches

Multiple Applications Support

The module automatically detects your application name from AH_SITE_GROUP. If you have multiple Acquia applications or need to override the detection, simply enter your application name in the configuration form. Learn more about Acquia application management.

Usage Examples

Web Interface:

Navigate to Configuration → Acquia Purge Varnish → Purge varnish and click the purge button.

Drush Commands:

# Purge all domains in current environment
drush apv-purge --domain=all

# Purge only current domain
drush apv-purge --domain=current

# Check status before purging
drush apv-status

# Test credentials
drush apv-test

# List all available domains
drush apv-domains --format=json

Automation (Post-Deployment Hook):

#!/bin/bash
# hooks/common/post-code-deploy/purge-varnish.sh
site="$1"
target_env="$2"
drush @$site.$target_env apv-purge --domain=all

Permissions

Grant the "Administer Acquia Purge Varnish" permission to appropriate roles at:

People → Permissions (/admin/people/permissions)

This permission controls access to configuration, manual purging, and all Drush commands.

Modern Architecture

• Drupal 10, 11 and 12 – Built on current Drupal APIs; the 3.0.2 release declares Drupal 12 support
• Dependency Injection – Service-based architecture throughout
• Strict Type Safety – PHP 8 strict types for better reliability
• Configuration Schema – Properly defined configuration structure
• Comprehensive Error Handling – Graceful handling of API failures
• PSR-4 Autoloading – Standard PHP autoloading practices

Documentation

• Acquia Cloud API v2 Documentation
• Acquia Cloud Platform Documentation
• Drupal Guzzle HTTP Client

Upgrade from Previous Versions

Upgrading includes automatic migration:

• Permission machine name updated automatically via update hook
• All existing configuration preserved
• New Drush commands immediately available
• Backward compatible with existing integrations

Legal Disclaimer

This module has not been developed, maintained, or endorsed by Acquia Inc. This is an independent open-source project with no affiliation to Acquia Inc. The module integrates with the publicly available Acquia Cloud Platform API as documented at cloudapi-docs.acquia.com.

Support and maintenance

Questions, ideas, and bug reports are welcome. Please use this project’s issue queue so discussions and solutions remain available to the Drupal community.

Maintainers monitor issues, but response times depend on availability.

Developed and maintained by Alaa Haddad of Flash Web Center, LLC.

AI disclosure: AI tools assisted with drafting and reviewing this project description. The maintainer verified the final content against the project source.