Magento Block HTML and Full Page Caching

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

The View Model Cache Tags documentation builds on these concepts, explaining 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. FPC dramatically reduces server load by serving cached responses without involving the Magento application.

Edge Side Includes (ESI) Cache

Caches page fragments assembled "at the edge" by a reverse proxy like Varnish. ESI allows mostly-static pages to include dynamic blocks (e.g., mini-cart) that are cached separately with different Time-to-Live (TTL) values. 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 removes stale cached content. Magento uses cache tags to group related cache records for collective invalidation.

How Cache Tags Work

Cache tags are string identifiers that associate cache records with their contained data. 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 mapping tags to cache record IDs. During invalidation, 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, similar to 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 then 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 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/)

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 cache tags that 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, favoring generic Template blocks with view models providing data. 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, view models cannot 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.