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.2.0(1mo ago)0141MITPHP

Since Feb 13Pushed 1mo 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 today

READMEChangelogDependencies (9)Versions (6)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

38

—

LowBetter than 83% of packages

Maintenance92

Actively maintained with recent releases

Popularity7

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity38

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 ~25 days

Total

5

Last Release

38d 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 (7 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.4M1](/packages/fastly-magento2)[mollie/magento2

Mollie Payment Module for Magento 2

1131.9M16](/packages/mollie-magento2)[loki/magento2-components

Core module for defining Alpine.js components with advanced AJAX features

1011.8k26](/packages/loki-magento2-components)[buckaroo/magento2

Buckaroo Magento 2 extension

32420.3k8](/packages/buckaroo-magento2)[imi/magento2-friendly-captcha

Friendly Captcha integration for Magento2

19131.4k](/packages/imi-magento2-friendly-captcha)[mage-os/module-inventory-reservations-grid

Add a grid with the list of inventory reservations.

1615.9k](/packages/mage-os-module-inventory-reservations-grid)

PHPackages © 2026

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