feat: Add article about adding custom header and footer

[mitelg]

Due to ESI loading customizing the header and footer does not work like in SW6.6 anymore. This should explain on how to extend them with SW6.7

Closes shopware/shopware#8604

[JoshuaBehrens]

How will dynamic access work for the navigation that way, when no rules (which feels like page data to me) can influence navigation elements? I assume people built similar things and need to understand. Otherwise we will just find plugins in the store, that disable the use of ESI as it is like this in the documentation

[david-strauch]

@mitelg

While I understand the motivation behind introducing ESI for header and footer – longer cache lifetime and better performance – I see a critical issue that must be addressed, especially in the context of Shopware's large and diverse plugin ecosystem.

The current solution forces developers to either remove ESI entirely or move all customizations into the base_esi_header or base_esi_footer blocks. This creates a dangerous bottleneck in terms of inheritance and extension possibilities.

Let me illustrate this with a realistic scenario:

Example Extension 1 – Shopware 6.6:
A plugin modifies the header and adds some dynamic content before the main header structure:

{% block base_header_inner %}
    {# ... foobar – my dynamic* content before header #}

    {{ parent() }}
{% endblock %}

(dynamic means: custom field output, controller response, login state-dependent content, etc.)

Now, with ESI, this approach breaks.

---

Example Migration of Extension 1 – Shopware 6.7:
To preserve the customization, the developer decides to inject the content into the new base_esi_header block:

{% block base_esi_header %}
    {# ... foobar – my dynamic content before header #}

    {{ parent() }}
{% endblock %}

So far, so good – until another extension enters the game.

---

Example Extension 2 – Shopware 6.7:
Another plugin, independently developed, follows the recommendation from the documentation and replaces the entire block with a static include:

{% block base_esi_header %}
    {% sw_include '@Storefront/storefront/layout/header/header.html.twig' %}
{% endblock %}

As a result, Extension 1 and its content are gone.

---

This is a real issue, not just a theoretical one. In a plugin-rich environment like Shopware's, this pattern creates massive incompatibilities and makes it impossible to rely on layered inheritance – one of the key features of the Twig templating system and the Shopware theme system.

• The base_esi_header block is now a hotspot – every plugin that touches the header needs to deal with it.
• There’s no room for safe inheritance unless every plugin behaves like a good citizen – which can’t be guaranteed.
• This will cause plugin breakages.

Therefore, I ask you to actively address this issue again.
shopware/shopware#8136

And if that is not an option, add more granular blocks within the ESI-loaded header and footer templates. For example:

• base_esi_header_before
• base_esi_header_inner
• base_esi_header_after

This would mirror the previous block structure and allow multiple plugins to safely inject their content without overwriting each other or breaking ESI logic.

This ESI approach, while technically elegant, has not been fully thought through in terms of developer experience and plugin compatibility. Given Shopware's commitment to extensibility, this decision needs to be revisited – or at least softened – before 6.7 reaches stable release.

Let’s not sacrifice the flexibility of the system in favor of a performance gain that might only be marginal in real-world setups.

[david-strauch]

Another important point to consider is how long this kind of implementation can realistically hold in a system as modular and extensible as Shopware.

Given the sheer number of extensions and custom implementations out there, it’s very likely that every second or third project will contain at least one plugin that modifies the header or footer in a way that renders the ESI include unusable or is forced to override it.

If enough plugins disable or bypass the ESI logic to keep their features working, the intended performance benefits are quickly lost across the ecosystem – and the ESI integration becomes more of a theoretical construct than a practical solution.

In other words: If this approach isn’t easily extendable and conflict-safe, it won’t be widely adopted. And if most developers end up turning it off, the effort might have been in vain.

[mitelg]

hey @david-strauch

thanks again for your valid feedback. We will revisit this again, as already mentioned in the issue.

[mitelg]

How will dynamic access work for the navigation that way, when no rules (which feels like page data to me) can influence navigation elements? I assume people built similar things and need to understand. Otherwise we will just find plugins in the store, that disable the use of ESI as it is like this in the documentation

@JoshuaBehrens Dynamic Access works out of the box. As soon as a rule is applied, the cache is disabled (cart and customer stuff)

[JoshuaBehrens]

@JoshuaBehrens Dynamic Access works out of the box. As soon as a rule is applied, the cache is disabled (cart and customer stuff)

A bit sad but I can understand, that one does not want to have super many permutation of rule ids in cache keys

[mitelg]

hey @JoshuaBehrens @david-strauch

I updated the article due to the latest changes I made here: shopware/shopware#8827

Would be cool, if you could have a look again

[david-strauch]

@mitelg For me, this works. I'm glad we found such a good solution. 🙌

Thanks to everyone for looking into this and coming up with a solution.

[Isengo1989]

Thx for the PR @mitelg 👍