Skip to main content
Version: v1

Twig CS Fixer

The Twig CS Fixer repository describes the tool as follows:

A tool to automatically fix Twig Coding Standards issues

Twig CS Fixer checks Twig templates for the formatting problems PHPCS catches in PHP: indentation, spacing around delimiters and operators, trailing whitespace, quote style, and trailing commas. Most of its rules can also fix what they find. Vortex comes with a pre-configured Twig CS Fixer ruleset for Drupal projects.

This page is for developers who write Twig templates in custom modules or themes. It shows how to lint and fix the templates, what the shipped ruleset enforces, and how to ignore a rule.

Usage​

Check for violations​

To check the templates, run 1 of the following commands:

# Lint all front-end code: Twig, JavaScript and CSS.
ahoy lint-fe

Confirm that the check passed: Twig CS Fixer prints a summary that starts with [OK] Files linted: and ends with errors: 0.

Fix violations​

To fix the violations that have an automatic fix, run 1 of the following commands:

# Fix all front-end lint issues.
ahoy lint-fe-fix

Configuration​

See the Twig CS Fixer configuration reference.

All global configuration lives in the .twig-cs-fixer.php file.

The ruleset uses the TwigCsFixer standard with a 2-space indent. It also turns on the rules that can't fix what they find, which Twig CS Fixer skips by default, so lint reports problems such as badly named variables too. It registers Drupal's trans tag parser as well, so templates that use {% trans %} blocks parse.

Targets include custom modules and themes.

To add or remove targets, add or remove the $finder->in() calls in .twig-cs-fixer.php:

$finder = new TwigCsFixer\File\Finder();
$finder->in(__DIR__ . '/web/modules/custom');
$finder->in(__DIR__ . '/web/themes/custom');

Ignoring​

To exclude a directory from linting, call $finder->exclude() in the .twig-cs-fixer.php file. The call drops the directory from the set of linted files and leaves every rule enabled:

$finder->exclude('myCustomDirectory');

Every error has an identifier in the form A.B:C:D, where:

  • A: the rule short name (mainly made from the class name)
  • B: the error identifier (like the error level or a specific name)
  • C: the line the error occurs on
  • D: the position of the token in that line

All 4 parts are optional: A, A.B, A.B:C, A.B:C:D, A:C, A:C:D, and A::D all work.

To find the identifier of an error you want to ignore, run Twig CS Fixer with the --debug option. ahoy lint-fe doesn't pass extra options to the linters, so run the following command instead:

docker compose exec cli vendor/bin/twig-cs-fixer lint --debug

In debug mode, each reported error starts with its identifier, followed by the message:

VariableName.Error:1:8 -- The var name must use snake_case; expected page_title.

To ignore all Twig CS Fixer rules in a file, add this comment to the file header:

{# twig-cs-fixer-disable #}

To ignore a specific rule in a file, add this comment to the file header:

{# twig-cs-fixer-disable A.B:C:D #}

Twig CS Fixer doesn't support ignoring code blocks.

To ignore rules for a single line, add this comment at the end of it:

{{ token }} {# twig-cs-fixer-disable-line A.B:C:D #}

To ignore rules for the next line only, add this comment on the line before it:

{# twig-cs-fixer-disable-next-line A.B:C:D #}
{{ token }}

Continuous integration​

Twig CS Fixer runs in the lint job of the continuous integration pipeline and fails the build on violations.

Ignoring failures​

To let the build pass anyway, set the VORTEX_CI_TWIG_CS_FIXER_IGNORE_FAILURE CI variable to 1. Twig CS Fixer still runs and prints every violation in the job log, so you can see what you're letting through.

➡️ See Continuous integration > Ignore tool failures