Download the PHP package machinateur/twig-block-validator without Composer

Twig Block Validator (for Shopware 6)

A twig block validator, inspired by the Shopware 6 IntelliJ plugin's twig block versioning. Pure PHP.

Inspiration

After visiting SCUC 2025 in Cologne, where it was mentioned and recommended multiple times, I held the idea that making twig-block validation possible via CLI would be a great help with CI for large shopware projects.

When dealing with many plugins and templates, it can get confusing quite fast. Let this tool help you with those twig blocks and validate if they're still up to date with their parent's content.

It also provides a way to automatically add and update the block version comment on your templates.

This project is still an early version!

It's missing some guardrails, so edge-cases might still lead to internal errors or bugs.

Installation

Requirements:

• PHP 8.2 or above
• Twig version ^3.15
• At least Shopware 6.4 (optional)

In your shopware project or plugin, run:

Also make sure the bundle is available in the desired environments, usually dev and test. So in config/bundles.php:

Usage

This tool may also be used without Shopware, it supports both.

Examples with Shopware

Annotate whole project

Use the following commands to execute the validator for an existing Shopware Storefront project.

The above command will load all available templates based on the debug:twig command (JSON output), then validate @DemoVendor/basecom/demo-plugin/src/Resources/views.

The above command will load all available templates based on the debug:twig command (JSON output), then annotate @DemoVendor/basecom/demo-plugin/src/Resources/views and output the changed templates to var/twig-block-validator/templates. Omit the path, to do update annotations in-place.

Next, those can be used to patch or compare the template source code, which is typically tracked via a VCS.

Validate the templates/nested dir

To validate against the dev-dependency shopware/storefront:^6.4 installed at vendor/shopware/storefront/Resources/views, expecting version 6.6 in the comments in tests/nested/ (__main__ as default namespace), run:

Here's the example template that would produce the above errors:

I just generated a random SHA265 for this test.

It's also possible to use twig-block here, but since this was inspired by Shopware's PhpStorm plugin, shopware-block is also supported. Which one is used is determined by shopware/storefront being installed (this is checked using composer).

In general, the version part of the comment is recommended, but since this tool is not strictly limited to working with shopware, it is not enforced. The provided version (-r flag) will be the default version, if none is set for a block. If not given, it will try to use the current shopware version, if available from the kernel.

Annotate @Storefront itself

The following command will go through the templates of shopware/storefront, put the annotation comment for those blocks, that extend another template (and therefor have a parent), and finally write the changed templates to ./var/cache/twig-block-validator/views.

This will also work, and annotate the storefront amongst its own templates. Just an experiment I tried.

How to validate

The validation can be performed by calling the CLI command twig:block:validate. Here's it's synopsis:

How to annotate

The annotation can be performed by calling the CLI command twig:block:annotate. Here's it's synopsis:

Caution! Always back up your templates and use a VCS. A bug or user error can cause permanent loss of data!

Which CLI to use

There are a total of four different CLIs available:

• bin/console: A symfony console application.
  • Runs a symfony kernel with symfony framework and debug commands (in dev or test).
  • Only supports the twig extensions that are available in the symfony context.
• bin/twig-block-validate: A symfony command application.
  • Runs only the twig:block:validate command as standalone application.
  • Only supports the twig extensions that are available in the symfony context.
• bin/twig-block-annotate: A symfony command application.
  • Runs only the twig:block:annotate command as standalone application.
  • Only supports the twig extensions that are available in the symfony context.

These can be copied to the bin/ directory of your project (if not already present).

Shopware test container

I've put in a small docker-compose setup, at tests/shopware/ which may be used to test against a real shopware instance.

Standalone

Note: The phar is still experimental, and does not support integrated use with shopware projects (yet).

The tool can be used as standalone, phar or source, for example in CI pipelines:

PHP is required. The source archive will need composer to be available and may also be used instead of git clone, when not available in your environment.

Find the source archive and prebuilt phar attached to the latest release.

Build the phar

This instruction requires box to be installed globally.

License

It's MIT.