Skip to content

Document Twig block versioning in Shopware Toolbox #2413

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Soner (shyim) wants to merge 1 commit into
base: main
Choose a base branch
from
+37 −0
Open

Document Twig block versioning in Shopware Toolbox #2413

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 37 additions & 0 deletions guides/development/tooling/shopware-toolbox.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,43 @@

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`.

Check warning on line 50 in guides/development/tooling/shopware-toolbox.md

View workflow job for this annotation

GitHub Actions / LanguageTool

[LanguageTool] guides/development/tooling/shopware-toolbox.md#L50 

Use “an” instead of ‘a’ if the following word starts with a vowel sound, e.g. ‘an article’, ‘an hour’. (EN_A_VS_AN)
Suggestions: `an`
URL: https://languagetool.org/insights/post/indefinite-articles/ 
Rule: https://community.languagetool.org/rule/show/EN_A_VS_AN?lang=en-US
Category: MISC
Raw output 
guides/development/tooling/shopware-toolbox.md:50:21: Use “an” instead of ‘a’ if the following word starts with a vowel sound, e.g. ‘an article’, ‘an hour’. (EN_A_VS_AN)
 Suggestions: `an`
 URL: https://languagetool.org/insights/post/indefinite-articles/ 
 Rule: https://community.languagetool.org/rule/show/EN_A_VS_AN?lang=en-US
 Category: MISC

#### Inspections

| Inspection | Enabled by default | Reported when |
|---|---|---|
Comment on lines +52 to +55
| 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
Expand Down
Loading