From 417c5a0d6b80d37c881bb5995a40bee730217a65 Mon Sep 17 00:00:00 2001 From: Soner Sayakci Date: Thu, 30 Jul 2026 16:49:55 +0200 Subject: [PATCH 1/3] Document Twig block versioning in Shopware Toolbox Co-Authored-By: Claude Fable 5 --- .../development/tooling/shopware-toolbox.md | 37 +++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/guides/development/tooling/shopware-toolbox.md b/guides/development/tooling/shopware-toolbox.md index 5a91664212..88afc4a655 100644 --- a/guides/development/tooling/shopware-toolbox.md +++ b/guides/development/tooling/shopware-toolbox.md @@ -34,6 +34,43 @@ Multiple live templates for development. Use Cmd/Ctrl + J to view all live templ Inspection to show an error when an abstract class is used incorrectly in the constructor (guideline check). +### Twig block versioning + +When you override a Twig block with `sw_extends`, the override can silently become outdated. A Shopware update may change the upstream block, for example with an accessibility fix, and nothing tells you that your copy no longer matches. Twig block versioning records which version of the upstream block your override is based on and warns you when the upstream block changes. + +The plugin stores this information in a comment above the block: + +```twig +{# shopware-block: c1954b12f0c4...@v6.6.6.0 #} +{% block base_body_skip_to_content %} + ... +{% endblock %} +``` + +The comment contains a SHA-256 hash of the upstream block content and the installed version of the composer package that provides the template. This works for Shopware core templates and for third-party extensions in `vendor` or `custom/plugins`. + +#### Inspections + +| Inspection | Enabled by default | Reported when | +|---|---|---| +| The upstream block has changed | Yes | The recorded hash no longer matches the upstream block. Check that your override is still correct. | +| The upstream block has been removed | Yes | The block no longer exists upstream. Check that your override is still needed. | +| Twig block is deprecated | Yes | The upstream block is marked as deprecated and will be removed in a future version. | +| Shopware versioning block comment is missing | No | A block override has no versioning comment yet. | + +#### Intentions + +Place the cursor on a block and press Alt+Enter (macOS: Option+Enter): + +* **Add/Update the Shopware 6 versioning comment** writes or refreshes the `shopware-block` comment for the block. +* **Show Twig block difference** opens a diff between your override and the current upstream block, so you can review what changed after an update. + +#### Add versioning comments to a whole project + +Enable the inspection *Shopware versioning block comment is missing* in *Settings → Editor → Inspections*, then run *Code → Inspect Code*. Apply its quick fix to add versioning comments to all template files at once. + +For more background, read the [Twig block versioning announcement](https://www.shopware.com/en/news/twig-block-versioning-in-shopware-phpstorm-plugin/). + ### Auto-completion * Admin components From 072369fc70873c47ae1bd3f3d839c167af41ff86 Mon Sep 17 00:00:00 2001 From: Su <112690947+sushmangupta@users.noreply.github.com> Date: Fri, 31 Jul 2026 10:48:09 +0200 Subject: [PATCH 2/3] Apply suggestions from code review Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- guides/development/tooling/shopware-toolbox.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/guides/development/tooling/shopware-toolbox.md b/guides/development/tooling/shopware-toolbox.md index 88afc4a655..cfbbb7fe7b 100644 --- a/guides/development/tooling/shopware-toolbox.md +++ b/guides/development/tooling/shopware-toolbox.md @@ -51,6 +51,8 @@ The comment contains a SHA-256 hash of the upstream block content and the instal #### Inspections +The following table lists the available inspections, their default state, and when they are reported: + | Inspection | Enabled by default | Reported when | |---|---|---| | The upstream block has changed | Yes | The recorded hash no longer matches the upstream block. Check that your override is still correct. | From 76bd5829c898e45482b3585e12abc273e3a9abf2 Mon Sep 17 00:00:00 2001 From: Su <112690947+sushmangupta@users.noreply.github.com> Date: Fri, 31 Jul 2026 10:48:29 +0200 Subject: [PATCH 3/3] Update guides/development/tooling/shopware-toolbox.md --- guides/development/tooling/shopware-toolbox.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/development/tooling/shopware-toolbox.md b/guides/development/tooling/shopware-toolbox.md index cfbbb7fe7b..8a9dbc3554 100644 --- a/guides/development/tooling/shopware-toolbox.md +++ b/guides/development/tooling/shopware-toolbox.md @@ -62,7 +62,7 @@ The following table lists the available inspections, their default state, and wh #### Intentions -Place the cursor on a block and press Alt+Enter (macOS: Option+Enter): +Place the cursor on a block and press **Alt+Enter** (macOS: **Option+Enter**): * **Add/Update the Shopware 6 versioning comment** writes or refreshes the `shopware-block` comment for the block. * **Show Twig block difference** opens a diff between your override and the current upstream block, so you can review what changed after an update.