Skip to main content
Last Reviewed: December 13, 2022

Caching: Advanced Topics

Advanced details about Pantheon's edge caching layer, cookies, and PHP sessions.


Allow a User to Bypass the Cache

Pantheon supports setting a NO_CACHE cookie for users who should bypass the cache. When this cookie is present, the Pantheon Global CDN will neither get the user's response from any existing cache nor store the response from the user into the cache.

Agency WebOps Training

Learn industry best practices for caching, how to take advantage of them on the platform, and troubleshooting common issues with help from the experts at Pantheon.

This allows users to immediately see comments or changes they've made, even if they're not logged in. To best achieve this, we recommend setting the NO_CACHE cookie to exist slightly longer than the site's page cache. This setting allows content contributors to resume using the cached pages once all cached pages have been updated.

Warning:
Warning

Pantheon does not support manually editing and updating the Varnish Configuration Language (VCL). We use a standard VCL for all sites on the platform. Requests for changes/updates to the standard VCL are accepted for consideration, but we do not guarantee change requests will be implemented.

Disable Caching for WordPress Sites in a Dev Environment

Follow the steps below to disable caching for WordPress sites in a Dev environment. Refer to Review Response Caching in our Frontend Performance guide for more information about caching on the Pantheon platform.

  1. Open the WordPress dashboard, click Settings, and then click Pantheon Page Cache.

  2. Set max-age (Time to Live) to 0.

Ignoring GET Parameters

For the purpose of optimizing cache hits for identical content, the Global CDN ignores any GET parameter prefixed with __ (two underscores) or utm_ in determining the cache key. This optimization is compatible with services such as Google Analytics and AdWords that use these query parameters solely for tracking and do not alter the page content returned by the application container. The double-underscore prefix for parameter keys and cookie names is a standard convention used by frontend code to indicate a value that can be safely ignored on the back-end.

For example, ?__dynamic_id=1234 is ignored, while ?dynamic_id=1234 and ?_dynamic_id are considered distinct pages.

The query parameters are still passed to the application container; however, the values are replaced with PANTHEON_STRIPPED to indicate that cache optimization is in effect for this parameter. Avoid using these parameters in ways that alter content in the response.

For more information, see PANTHEON_STRIPPED GET Parameter Values.

External Authentication (e.g. Facebook login)

If your site or application requires Facebook authentication, we have added exceptions for this to allow users to register and log in. In the event you are having problems with another external authentication service, please contact us and let us know what service you are having issues with.

Manually Expiring Cache for Static Assets

Pantheon sets an cache max-age of one year for static assets (e.g. CSS, JS, Images, PDFs) on Live and Test environments with the HTTP header of cache-control: max-age=31622400. This setting improves page load times as a visitor browses a site across pages that make requests to the same assets.

However, this setting can prevent changes to static assets from being immediately visible to a client's browser. So select one of the options below to ensure a client's browser receives a new version of any static asset after clearing a site's cache:

  • Rename the file
  • Request the file with an updated query parameter. For example, you can version a css file by linking to it as style.css?v=1.1

For CSS or JavaScript changes, Drupal and WordPress each offer methods to ensure a new file name will be created automatically any time a site's cache is cleared:

Use the built-in option found in the Drupal dashboard at /admin/config/development/performance.

Clear the site cache after deleting static files. Clear the Global CDN cache, if deleted static files are still visible in the live environment after clearing your site cache.

Info:
Note

Dev and Multidev environments always set an HTTP header to cache-control: no-cache, must-revalidate so that changes to CSS and other assets are always reloaded as developers update them.

Using Your Own Session-Style Cookies

Pantheon passes all cookies beginning with SESS that are followed by numbers and lowercase characters back to the application. When at least one of these cookies is present, the Global CDN will not try to respond to the request from its cache or store the response.

Drupal uses SESS-prefixed cookies for its own session tracking, so be sure to name yours differently if you choose to use one. Generally, SESS followed by a few words will work.

Correct: SESSmysessioncookie, SESShello123, SESSletsgo

Incorrect: SESS_hello, SESS-12345, mycustomSESS, Sessone, sess123testing, SESSFIVE

Pantheon allows developers to control the length of sessions. There are two pieces: the lifetime of the cookie and the lifetime of the session itself.

Session cookie lifetime is configured using the session.cookie_lifetime PHP setting. If set to 0, the cookie is deleted when the user closes their browser. Session cookie lifetime is set to 2,000,000 seconds in Drupal's default.settings.php and in Pantheon's PHP configuration.

Drupal's session garbage collection uses the session.gc_maxlifetime PHP setting when deleting expired sessions from the sessions database table. Session max lifetime is set to 200,000 seconds in Drupal's default.settings.php and in Pantheon's PHP configuration.

For additional details and examples on how to set cookie lifetimes and garbage collection manually, see the documentation within default.settings.php.

Session cookie lifetime and session garbage collection can be configured as session.storage.options parameters in a services.yml file. To override core session behavior, create a copy of the services.yml file (see Creating a services.yml File for Drupal), and adjust the gc_maxlifetime and cookie_lifetime values as needed.

Geolocation, Referral Tracking, Content Customization, and Cache Segmentation

A site may need to deliver different content to different users without them logging in or starting a full session (either of which will cause them to bypass the page cache entirely). Pantheon recommends doing this on the client side using browser detection, orientation, or features like aspect ratio using HTML5, CSS3, and JavaScript. Advanced developers can also use STYXKEY.

Using Modernizr

Modernizr is a JavaScript library that detects HTML5 and CSS3 features in the user's browser. This will also allow requests to have the benefit of being saved in the Global CDN and rendering correctly, depending on the requirements. Modernizr is available as a Drupal module or a WordPress plugin.

Device Detection

We do not recommend using cookies that are passed to the backend for mobile theme detection and configuration. This will cause issues scaling requests within your site in case of any load or traffic spikes, as it requires at least the initial hit to make it to the backend before anonymous traffic can be cached by the Global CDN. If you receive more uncached visitors than your Nginx and PHP processes, it can result in timeouts and server errors.

Best Practice Recommendations

We recommend handling mobile detection using Responsive Web Design (RWD) techniques with HTML5, CSS3, and JavaScript. This will avoid the need to compromise potential scalability in order to scale traffic. HTML5 and CSS3 is the high performance route, as you save on the back-end load and browsers.

Issue Implementing the mobile site on a different domain, subdomain, or subdirectory from the desktop site.

Recommended Solution While Google supports multiple mobile site configurations, creating separate mobile URLs greatly increases the amount of work required to maintain and update your site, and introduces possible technical problems. You can simplify things significantly by using responsive web design and serving desktop and mobile on the same URL. Responsive web design is Google’s recommended configuration.

More information on mobile site best practices can be found in Google's official developer documentation:

A full list of the devices and their support for HTML5 is available on https://html5test.co:

Using STYXKEY

The Global CDN only passes cookies in your allowlist. To use custom cookies with Drupal or WordPress, you can set a cookie beginning with STYXKEY followed by one or more alphanumeric characters, hyphens, or underscores.

For example, you could set a cookie named STYXKEY_country to ca or de and cache different page content for each country. A site can have any number of STYXKEY cookies for varying content.

In your code, remember to first check whether the incoming request has the STYXKEY cookie set. If it does, generate the different version of the page, but don't set the cookie again, i.e. don't respond with another Set_Cookie: header. If the code tries to set the cookie again, the Global CDN will not cache that page at all, as it cannot cache a response that contains a Set_Cookie: header.

Info:
Note

STYXKEY is not a replacement for responsive design.

Examples of STYXKEY cookie names:

  • STYXKEY_mobile-ios: Delivers different stylesheets and content for iOS devices

  • STYXKEY_european_user: Presents different privacy options to E.U. users

  • STYXKEY_under21: Part of your site markets alcohol and you want to change the content for minors

  • STYXKEY_school: Your site changes content depending on the user's school affiliation

Invalid names that won't work:

  • STYXKEY: Needs something after the STYXKEY text

  • styxkey_android: The text STYXKEY must be uppercase

  • STYX-KEY_android: The text STYXKEY cannot be hyphenated or contain other punctuation

  • STYXKEY.tablet: The only valid characters are a-z, A-Z, 0-9, hyphens ("-"), and underscores ("_")

  • tablet_STYXKEY: The cookie name must start with STYXKEY

Public Files and Cookies

Pantheon strips cookies from requests made to public files served from sites/default/files in Drupal and wp-content/uploads in WordPress. This allows the Global CDN to cache the response.

File Suffixes and Cookies

Pantheon strips cookies for any file ending with the following extensions, even if the file is dynamically generated by Drupal or WordPress:

png | gif | jpeg | jpg | ico | bmp | tif | tiff | webp | swf | css | js | woff | woff2 | svg | ttf | otf | eot

404s

Pantheon’s default is to not cache 404s, but if your application sets Cache-Control:max-age headers, the Global CDN will respect them. Depending on your use case, that may be the desired result.

Drupal’s 404_fast_* configuration does not set caching headers. Some contributed 404 modules include cache-friendly headers, which will cause a 404 response to be cached.

Environment Access Locked

If you're using the Security tool within the Pantheon Site Dashboard to lock an environment, the Global CDN will not cache responses. Disable basic authentication by setting environment access to Public.

The code block below shows the Cache-Busting Cookie Patterns section of Pantheon's Varnish configuration (.vcl) file for your reference. Advanced Drupal and WordPress developers should reference this code if they have any questions regarding what cookie patterns the Global CDN will not cache:

NO_CACHE
S+ESS[a-z0-9]+
fbs[a-z0-9_]+
SimpleSAML[A-Za-z]+
PHPSESSID
wordpress[A-Za-z0-9_]*
wp-[A-Za-z0-9_]+
comment_author_[a-z0-9_]+
duo_wordpress_auth_cookie
duo_secure_wordpress_auth_cookie
bp_completed_create_steps # BuddyPress cookie used when creating groups
bp_new_group_id # BuddyPress cookie used when creating groups
wp-resetpass-[A-Za-z0-9_]+
(wp_)?woocommerce[A-Za-z0-9_-]+
amazon_Login_[A-Za-z0-9_]+

Note that wp-wpml_* cookies are an exception to the above WordPress pattern. Pantheon will treat language-preference cookies from WPML as cache varying cookies.