Pantheon Advanced Page Cache
A bridge between Drupal cache metadata and Pantheon Global CDN that enables automatic edge cache invalidation based on Drupal's cache tags system.
pantheon_advanced_page_cache
Install
composer require 'drupal/pantheon_advanced_page_cache:^2.3'
Overview
Pantheon Advanced Page Cache module connects Drupal's robust cache metadata system to Pantheon's Global CDN infrastructure. When enabled, it automatically converts Drupal's internal cache tags into HTTP Surrogate-Key headers that the Pantheon CDN understands.
This enables intelligent, granular cache invalidation at the edge. When underlying data changes in Drupal (such as nodes being updated, taxonomy terms modified, or user permissions changed), only the relevant cached pages are cleared from the CDN - rather than purging the entire cache.
The module requires no configuration for basic operation. Simply enable it on a Pantheon-hosted site and it begins working immediately, leveraging the cache metadata that Drupal 8+ already provides. This zero-configuration approach makes it ideal for maximizing cache hit rates while ensuring content freshness.
Features
- Automatically converts Drupal cache tags to Surrogate-Key HTTP headers for Pantheon Global CDN integration
- Enables granular edge cache invalidation - only affected pages are purged when content changes
- Zero configuration required - works immediately upon installation on Pantheon-hosted sites
- Enforces 25KB header size limit to prevent 502 errors caused by excessively long headers
- Logs warnings when cache tag limits are exceeded to help administrators identify optimization opportunities
- Supports optional legacy behavior for list tag handling via configuration
- Integrates seamlessly with Drupal's Cache API and cache tag invalidation system
Use Cases
High-Traffic News Website
A news site hosted on Pantheon can enable this module to ensure articles are served from the edge CDN globally while still being purged immediately when editors update content. When an article is edited, only that specific article's cached pages are invalidated - not the entire cache.
E-commerce Product Catalog
An e-commerce site benefits from intelligent cache invalidation. When a product's price or availability changes, all pages displaying that product are automatically purged from the CDN, while unrelated pages remain cached for optimal performance.
Content Listing Pages
When new articles are published, listing pages like the front page or category pages are automatically purged (with default settings). This ensures visitors see fresh content without manual cache clearing.
User Permission Changes
When user permissions or roles are modified, affected cached pages are automatically invalidated, ensuring users always see content appropriate to their access level.
Tips
- Use curl with the Pantheon-Debug:1 header to inspect Surrogate-Key-Raw headers: curl -IH 'Pantheon-Debug:1' https://your-site.pantheonsite.io/
- Pages rendering many entities may exceed header limits - consider filtering cache tags using a custom event subscriber
- New installations automatically use recommended settings - only sites upgrading from 1.x need configuration changes
- The module works automatically with Drupal's built-in cache metadata - no code changes needed in most cases
- Combine with Views Custom Cache Tags for fine-grained control over Views-generated cache tags
- Check /admin/reports/dblog for warning messages about header size limits being reached
Technical Details
Drush Commands 1
drush config:set pantheon_advanced_page_cache.settings override_list_tags false
Disable list tag override behavior (recommended for sites upgrading from 1.x)
Troubleshooting 5
This is likely caused by the Surrogate-Key header exceeding size limits. The module caps headers at 25KB but other headers combined may exceed nginx's 32KB limit. Check Drupal logs for warning messages. Consider using custom code or Views Custom Cache Tags module to filter out redundant cache tags.
This indicates pages are rendering thousands of entities. Create a custom event subscriber with higher priority than the module's subscriber (priority > 0) to filter out unnecessary cache tags before they're added to the header. See the test module for an example implementation.
Run: drush config:set pantheon_advanced_page_cache.settings --input-format=yaml override_list_tags false - or uninstall and reinstall the module to get the new default behavior.
Pantheon strips the Surrogate-Key header before sending responses to clients. Use curl with the debug header to view the raw headers: curl -IH 'Pantheon-Debug:1' https://your-site.pantheonsite.io/
The module only functions on Pantheon-hosted sites where the pantheon_clear_edge_keys() function is available. On non-Pantheon hosting, the module gracefully does nothing.
Security Notes 3
- The module has 'covered' security advisory coverage from Drupal Security Team
- No sensitive data is exposed - Surrogate-Key headers only contain cache tag identifiers
- The module relies on Drupal's existing cache tag system and does not introduce new attack vectors