The feature-set of Authcache and its submodules can be divided into four subsystems:

Policy
Determines whether a page can be cached for the currently logged in user.
Variation
Ensures that a cached page is only delivered to users having the same set of privileges on a site.
Storage
Provides methods for storing fully rendered pages, ranging from the database backed default implementation through to high performance solutions like Redis and even Varnish.
Personalization
Simplifies the delivery of personalized fragments via lightweight Ajax or ESI callbacks.

The functionality is broken up into a sizable set of modules. This chapter gives an overview of the modules / APIs and relates them to one of the aforementioned subsystems.

Policy

The policy framework is built into the main Authcache module. The following key aspects of the policy can be customized via the administrative UI:

  • The list of roles which are cacheable. Users having one or more role which is not in this list are excluded from caching.
  • One or more rule set specifying which pages are excluded from the cache.

The Authcache Relation module provides a policy rule preventing pages to be cached when the Relation Entity Collector Block contains picked entities.

Beyond that it is possible to control which content-types can be cached or whether error-pages or Ajax requests are recorded.

By implementing one of the following hooks it is possible to fully customize the policy (documentation):

  • hook_authcache_request_exclude()
  • hook_authcache_account_exclude()
  • hook_authcache_cancel()
  • hook_authcache_preclude()

Variation

Typically a site looks different for authenticated users versus when it is accessed anonymously. Even for authenticated users having different roles, the markup is most often not identical. Therefore, Authcache stores a separate set of pages for each user group having the same set of roles.

This is done by generating a hash value (the Authcache key) which is the same for all users having the same privileges. This key is prepended to the URL (serving as the cache object identifier) when a page is recorded in the cache.

It is possible to influence key calculation by implementing one of the following hooks (documentation):

  • hook_authcache_key_properties()
  • hook_authcache_key_properties_alter()

Sometimes it is also desirable to partition the page cache for anonymous users. For example when different variants of the front-page exist depending on the geographical region of the client (geoIP) or its browser language. In this case it is possible to even override the key generator for anonymous users using the authcache_key_generator variable by supplying a callable via settings.php. The default implementation simply returns $base_root. See #2348155-2: Integrate with locale cookie for an example.

Keep in mind that returning different content for the same URL might be interpreted as cloaking by crawlers, therefore in most cases it should be avoided.

Storage

Authcache provides support for a variety of storage backends. In order to be operational at least one of the following modules needs to be enabled and configured:

Authcache Builtin Storage Backend
By default uses the database to store cached pages. Can be configured to use a contrib cache class as discussed in Authcache 2 tuning guide - avoid the database
Authcache Varnish Storage Backend
Ensures that an appropriate Cache-Control header is set on cacheable responses such that a page can be stored savely by the Varnish gateway proxy. See Authcache 2 recipe: Upgrade to Varnish and ESI.

Authcache ships with experimental support for Boost as a cache backend. It is not recommended to use it in a production environment. The Authcache FS Cache Backend sandbox project provides an alternative filesystem based approach inspired by Boost. This is even more experimental and therefore only appropriate for developers willing to actively contribute to the project.

Storage backend modules need to implement the following hooks (documentation):

  • hook_authcache_backend_cache_save()
  • hook_authcache_backend_key_set()

The following handbook pages provide guidance on how to integrate third party storage backends:

Personalization

By far the largest amount of code deals with the delivery of personalized fragments via lightweight Ajax or ESI callbacks. Most sites will not get away without a minimal amount of personalization.

The core of this subsystem is formed by the Authcache Personalization API. In addition at least one of the following markup substitution client modules needs to be enabled:

Authcache Ajax
Delivers lightweight personalized fragments via Ajax
Authcache ESI
See Authcache 2 recipe: Upgrade to Varnish and ESI.

Depending on the site structure and content one or more of the following modules need to be enabled also: