PHPackages                             hryvinskyi/magento2-esi-page-layout - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Caching](/categories/caching)
4. /
5. hryvinskyi/magento2-esi-page-layout

ActiveMagento2-module[Caching](/categories/caching)

hryvinskyi/magento2-esi-page-layout
===================================

Ensures correct theme context and cache segmentation for Varnish ESI block requests in multi-theme Magento setups

1.0.2(3mo ago)081MITPHP

Since Feb 13Pushed 2mo agoCompare

[ Source](https://github.com/hryvinskyi/magento2-esi-page-layout)[ Packagist](https://packagist.org/packages/hryvinskyi/magento2-esi-page-layout)[ RSS](/packages/hryvinskyi-magento2-esi-page-layout/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (2)Versions (4)Used By (0)

Varnish ESI Theme Context for Magento 2
=======================================

[](#varnish-esi-theme-context-for-magento-2)

Ensures correct theme context and cache segmentation for Varnish ESI block requests in multi-theme Magento setups.

Problem
-------

[](#problem)

When Varnish fetches ESI blocks via `/page_cache/block/esi`, the request does not carry any theme context. In a multi-theme store (e.g. `Vendor/base` and `Venor/balckfriday`), ESI blocks may be rendered and cached using the wrong theme, causing incorrect markup or broken styles.

Additionally, blocks with `ttl` are rendered inline during full-page generation even though they will be replaced by `` tags — wasting server resources.

Solution
--------

[](#solution)

This module solves both issues with three components:

### 1. Observer: `ProcessLayoutRenderElement`

[](#1-observer-processlayoutrenderelement)

Replaces the core `Magento\PageCache\Observer\ProcessLayoutRenderElement` (disabled in frontend scope). Adds an `esi_theme` parameter directly to the ESI URL during `` tag generation, so the theme path is carried through to the ESI request.

### 2. Plugin: `RestoreEsiContextPlugin`

[](#2-plugin-restoreesicontextplugin)

Before plugin on `Magento\PageCache\Controller\Block\Esi::execute()`. Reads `esi_theme` from the request, sets the design theme via `DesignInterface::setDesignTheme()`, and adds a layout cache key (`esi_theme_{path}`) so layout cache is segmented per theme.

### 3. Plugin: `SkipRenderLayoutElementPlugin`

[](#3-plugin-skiprenderlayoutelementplugin)

Around plugin on `Magento\Framework\View\Layout::renderNonCachedElement()`. When Varnish full-page cache is active and the page is cacheable, blocks with a TTL are skipped (return empty string) since they will be served via ESI includes instead.

Known Issues with Third-Party Modules
-------------------------------------

[](#known-issues-with-third-party-modules)

### Amasty: Incorrect Entity-Specific Handle Registration

[](#amasty-incorrect-entity-specific-handle-registration)

> **Warning:** Avoid using Amasty modules if you want your site to be solid and have good performance.

Amasty modules (`amasty/module-shop-by-brand`, `amasty/shopby`) have a bug in their category controllers where they call `addPageLayoutHandles()` with both `type` and `id` parameters in a single call without setting `$entitySpecific = false`:

```
// Amasty (BROKEN) — marks ALL handles as entity-specific, including page-type handles
$page->addPageLayoutHandles(['type' => $type, 'id' => $category->getId()], 'catalog_category_view');
```

Magento core does this correctly with separate calls:

```
// Magento core (CORRECT) — type handles are NOT entity-specific, only id handles are
$page->addPageLayoutHandles(['type' => $pageType], null, false);
$page->addPageLayoutHandles(['id' => $category->getId()]);
```

This causes `catalog_category_view_type_layered` to be registered as an entity-specific handle. Magento's `ProcessLayoutRenderElement` observer then strips it from ESI URLs via `array_diff()`, so when Varnish fetches the ESI block, the layout is loaded without the layered navigation handle, resulting in broken block rendering on category and brand pages.

Installation
------------

[](#installation)

```
composer require hryvinskyi/magento2-esi-page-layout
bin/magento module:enable Hryvinskyi_EsiPageLayout
bin/magento setup:di:compile
bin/magento cache:flush
```

Configuration
-------------

[](#configuration)

No configuration required. The module activates automatically when Varnish full-page cache is enabled.

Requirements
------------

[](#requirements)

- Magento 2.4.x
- PHP 8.1+

###  Health Score

35

—

LowBetter than 80% of packages

Maintenance83

Actively maintained with recent releases

Popularity7

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity36

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

3

Last Release

94d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/9294098?v=4)[Volodymyr Hryvinskyi](/maintainers/hryvinskyi)[@hryvinskyi](https://github.com/hryvinskyi)

---

Top Contributors

[![hryvinskyi](https://avatars.githubusercontent.com/u/9294098?v=4)](https://github.com/hryvinskyi "hryvinskyi (5 commits)")

### Embed Badge

![Health badge](/badges/hryvinskyi-magento2-esi-page-layout/health.svg)

```
[![Health](https://phpackages.com/badges/hryvinskyi-magento2-esi-page-layout/health.svg)](https://phpackages.com/packages/hryvinskyi-magento2-esi-page-layout)
```

###  Alternatives

[fastly/magento2

Fastly CDN Module for Magento 2.4.x

1564.2M1](/packages/fastly-magento2)[lizardmedia/module-varnish-warmer

Varnish Cache Warmer Magento2 module by Lizard Media

6276.8k](/packages/lizardmedia-module-varnish-warmer)[litespeed/module-litemage

LiteMage Full Page Cache for LiteSpeed Web Server

3254.8k](/packages/litespeed-module-litemage)[elgentos/magento2-varnish-extended

This extension extends the built-in Varnish functionalities

6510.9k](/packages/elgentos-magento2-varnish-extended)[vendic/module-optimize-cache-size

Magento 2 extension that reduces the number of cache keys by removing catalog\_product\_view\_id\_, catalog\_product\_view\_sku\_, catalog\_product\_view\_attribute\_set\_, catalog\_category\_view\_id\_ layout handles by default

3453.6k](/packages/vendic-module-optimize-cache-size)[redchamps/module-easy-cache-clean

Clean invalidated cache(s) easily in a Magento 2 store

2838.0k](/packages/redchamps-module-easy-cache-clean)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)