Skip to content

Magento Block HTML and Full Page Caching

This document explains Magento's multi-layered caching architecture, focusing on the view layer caching mechanisms that affect Hyvä theme development. Understanding these caching layers is essential for implementing proper cache invalidation and optimizing storefront performance.

The View Model Cache Tags documentation builds on these concepts to explain Hyvä's solution for associating cache tags with view models.

Magento Caching Layers Overview

Magento employs four distinct caching layers, each serving different purposes and using different storage backends:

Low-Level Cache

Stores configuration data, layout XML, EAV attribute definitions, and database query results. Typically backed by Redis or the file system. This cache operates within PHP and is cleared using bin/magento cache:clean or bin/magento cache:flush.

Full Page Cache (FPC)

Caches complete HTML page responses. Production environments typically use Varnish or Fastly as a reverse proxy cache. Development environments may use Redis or file-based FPC. The FPC dramatically reduces server load by serving cached responses without the Magento application.

Edge Side Includes (ESI) Cache

Enables caching of page fragments that can be assembled "at the edge" by a reverse proxy like Varnish. ESI allows mostly-static pages to include dynamic blocks (like the mini-cart) that are cached separately with a different Time-to-Live (TT). ESI is only available with Varnish-compatible FPC backends.

Browser Cache

The visitor's browser stores content locally, including static assets (JavaScript, CSS, images), Customer Section Data in localStorage, session cookies, and store view preferences. Browser cache behavior is controlled via HTTP headers and JavaScript.

These caching layers interact in complex ways, and understanding their relationships is critical for debugging cache-related issues.

Cache Invalidation with Cache Tags

When data changes in Magento, the caching system must remove stale cached content. Magento uses cache tags to group related cache records so they can be invalidated together.

How Cache Tags Work

Cache tags are string identifiers that associate cache records with the data they contain. A single cache record can have multiple cache tags, and a single cache tag can be associated with many cache records.

For example, every cache record containing product 123 data is tagged with cat_p_123. When product 123 is edited, Magento invalidates all cache records with that tag across all caching layers.

Cache Invalidation by Backend Type

Each caching backend handles tag-based invalidation differently due to their distributed nature:

Low-Level Cache Invalidation

Cache tags are stored in a backend-dependent index that maps tags to cache record IDs. When invalidation occurs, records are deleted synchronously within the same PHP process that triggered the cache clean command.

Full Page Cache Invalidation

FPC invalidation behavior depends on the backend:

  • Built-in FPC (Redis/File): Cache tags are stored via the X-Magento-Tags response header. Records are cleaned in-process like low-level cache records.
  • Varnish FPC: Cache tags are specified via the X-Magento-Tags response header as a comma-separated list. During invalidation, Magento sends an HTTP PURGE request with an X-Magento-Tags-Pattern header containing a regex pattern. Varnish evicts all records whose tags match the pattern.

ESI Cache Invalidation

ESI cache records use the same X-Magento-Tags header mechanism as Varnish FPC, since ESI fragments are stored within the Varnish cache.

Browser Cache Invalidation

Browser-stored content uses different invalidation strategies:

  • Cookies: Cleared server-side by setting the value to null or setting an expiry date in the past
  • LocalStorage (Customer Section Data): Refreshed by incrementing the private_content_version cookie, which triggers JavaScript to fetch fresh data
  • Static assets (JS, CSS, translations): Invalidated by changing the version hash in the URL path (e.g., /static/version1234567890/)

Cache TTL Expiration

In addition to tag-based invalidation, most cache records have a TTL (time-to-live) after which the cache backend automatically discards them.

Associating Cache Tags with Frontend Cache Records

This section focuses on frontend cache records relevant to Hyvä theme development: Block HTML cache, FPC records, and ESI records.

Block HTML Cache Tags

Blocks are responsible for declaring the cache tags that should invalidate their cached HTML output. The Magento\Framework\View\Element\AbstractBlock::getCacheTags() method returns an array of cache tag strings.

Subclasses can override this method to add entity-specific tags (e.g., product or category tags). Alternatively, cache tags can be set programmatically by calling $block->setCacheTags($tagsArray) before rendering.

The View Model Problem

Magento's architectural guidance discourages custom block classes in favor of generic Template blocks with view models providing data. However, this creates a cache tag problem: view models have no standard API to add cache tags to the block rendering them.

The workaround options are limited:

  • Call $block->setCacheTags() from within the template
  • Create a custom view model method that sets cache tags on the block
  • Avoid using Block HTML cache and rely solely on FPC

This limitation is why Magento core makes minimal use of Block HTML caching, preferring FPC for most caching needs. Hyvä solves this problem with View Model Cache Tags.

Full Page Cache and ESI Cache Tags

FPC and ESI cache tags use a different mechanism than Block HTML cache tags. Instead of getCacheTags(), blocks must implement Magento\Framework\DataObject\IdentityInterface with its single method getIdentities().

All identities returned by blocks rendered on a page are aggregated into the X-Magento-Tags response header, enabling Varnish to invalidate the cached page when any associated entity changes.

The Same View Model Problem

The IdentityInterface must be implemented by block classes, not view models. Since generic Template blocks cannot implement custom interfaces, there is no way for view models to contribute cache tags to FPC responses in standard Magento.

This architectural gap means pages using view models for data may not be properly invalidated when underlying data changes. Hyvä's View Model Cache Tags feature solves this problem by allowing view models to implement IdentityInterface and automatically adding their tags to page responses.

FPC Segmentation

Besides cache tags, FPC supports URL segmentation for serving different cached versions based on customer group, currency, or other context. This topic is outside the scope of this document. See this blog post on FPC segmentation for details.