Twig Style Guide

A mostly reasonable approach to Twig

This is a superset of the Official SensioLabs Twig Standards.

It should be compatible with the Drupal Twig Coding Standards.

Very heavily 'inspired' by airbnb/Javascript.

Table of Contents

1. Tags
2. Filters
3. Functions
4. Tests
5. Operators
6. Variables
7. Blocks
8. Comments
9. Whitespace
10. Commas
11. Naming Conventions
12. Resources
13. In the Wild
14. Translation
15. Contributors

Tags

⬆ back to top

Filters

• 2.1 String tokens to be used inside the replace filter should be marked with percentage signs.

  {# Bad. #}
  {{ sidekicks|replace('{{ robin }}', 'Dick Grayson') }}
  
  {# Good. #}
  {{ sidekicks|replace('%robin%', 'Jason Todd') }}

⬆ back to top

Functions

⬆ back to top

Tests

⬆ back to top

Operators

⬆ back to top

Variables

⬆ back to top

Blocks

• 7.1 Blocks that span multiple lines should have their opening and closing tags on their own lines.

  {# Bad. #}
  {% include '@components/component.image.twig' with {
    'src' = image.src,
    'alt' = image.alt,
    'attributes' = image.attributes,
    'sources' = image.sources,
  } only %}
  
  
  {# Good. #}
  {%
  include '@components/component.image.twig' with {
    'src' = image.src,
    'alt' = image.alt,
    'attributes' = image.attributes,
    'sources' = image.sources,
  } only
  %}
  
  {# Bad. #}
  {% set hero = {
    'firstName': 'Florence',
    'lastName': 'Nightingale',
    'inventorOf': ['coxcomb chart', 'modern nursing'],
  } %}
  
  {# Good. #}
  {%
  set hero = {
    'firstName': 'Florence',
    'lastName': 'Nightingale',
    'inventorOf': ['coxcomb chart', 'modern nursing'],
  }
  %}
  
  
  {# Bad. #}
  {{ foo
    |replace({ '_': ' ' })
    |title
    |default('foo') }}
  
  {# Good. #}
  {{
  foo
    |replace({ '_': ' ' })
    |title
    |default('foo')
  }}

⬆ back to top

Comments

⬆ back to top

Whitespace

• 9.1 Use soft tabs set to 2 spaces.

  {# Bad. #}
  {%
  set foo = [
  ∙∙∙∙name
  ]
  %}
  
  {# Bad. #}
  {%
  set foo = [
  ∙name
  ]
  %}
  
  {# Good. #}
  {%
  set baz = [
  ∙∙name;
  ]
  %}

• 9.2 Place 1 space before the leading brace.

  {# Bad. #}
  {%
  set dog={
    'age': '1 year',
    'breed': 'Bernese Mountain Dog',
  }
  %};
  
  {# Good. #}
  {%
  set dog = {
    'age': '1 year',
    'breed'': 'Bernese Mountain Dog',
  }
  %};

• 9.3 Place 1 space before the opening parenthesis in control statements (if, for etc.). Place no space between the argument list and the function name in function calls and declarations.

  {# Bad. #}
  {% if(isJedi) %}
    {% set enemy = 'sith' %}
  {% endif %}
  
  {# Good. #}
  {% if (isJedi) %}
    {% set enemy = 'sith' %}
  %}
  
  {# Bad. #}
  {{ jedi|default ('Yoda') }}
  
  {# Good. #}
  {{ jedi|default('Yoda') }}

• 9.4 Set off operators with spaces.

  {# Bad. #}
  {% set x=y+5 %}
  
  {# Good. #}
  {% set x = y + 5 %}

• 9.5 End files with a single newline character.

  {# Bad. #}
  {{ stuff }}

  {# Bad. #}
  {{ stuff }}↵
  ↵

  {# Good. #}
  {{ stuff }}↵

• 9.6 Use indentation when making long filter chains (more than 2 filter chains). Use a leading dot, which emphasizes that the line is a method call, not a new statement.

  {# Bad. #}
  {{ foo|upper|lower|title|default('foo') }}
  
  {# Bad. #}
  {{
  foo|
    upper|
    lower|
    title|
    default('foo')
  }}
  
  {# Good. #}
  {{
  foo
    |upper
    |lower
    |title
    |default('foo')
  }}
  
  {# Bad. #}
  {{
  foo|upper
    |lower|title
    |default('foo')
  }}
  
  {# Good. #}
  {{ foo|title|default('foo') }}

• 9.7 Do not pad your blocks with blank lines.

  {# Bad. #}
  {%
  
    set foo = 'bar'
  
  %}
  
  {# Bad. #}
  {% if baz %}
  
    {{ qux }}
  {% elseif %}
    {{ foo }}
  
  {% endif %}
  
  {# Good. #}
  {%
  set foo = 'bar'
  %}
  
  {# Good. #}
  {% if baz %}
    {{ qux }}
  {% elseif %}
    {{ foo }}
  {% endif %}

• 9.8 Do not add spaces inside parentheses.

  {# Bad. #}
  {{ foo|default( 'foo' ) }}
  
  {# Good. #}
  {{ foo|default('foo') }}

• 9.9 Do not add spaces inside brackets.

  {# Bad. #}
  {% set foo = [ 1, 2, 3 ] %}
  {{ foo.0 }}
  
  {# Good. #}
  {% set foo = [1, 2, 3] %}
  {{ foo.0 }}

• 9.10 Add spaces inside curly braces.

  {# Bad. #}
  {% set foo = {clark: 'kent'} %}
  
  {# Good. #}
  {% set foo = { clark: 'kent' } %}

• 9.11 Avoid having lines of code that are longer than 80 characters (including whitespace).

  Why? This ensures readability and maintainability.

  {# Bad. #}
  {% set foo = 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.' %}
  
  {# Bad. #}
  {% if victory|default %}{{ congratulations }}{% else %}{{ failure }}{% endif %}
  
  {# Good. #}
  {%
  set foo = 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed ' ~
    'do eiusmod tempor incididunt ut labore et dolore magna aliqua.'
  %}
  
  {# Good. #}
  {% if victory|default %}
    {{ congratulations }}
  {% else %}
    {{ failure }}
  {% endif %}

⬆ back to top

Commas

• 10.1 Leading commas: No.

  {# Bad. #}
  {%
  set story = [
    'once'
  , 'upon'
  , 'a'
  , 'time'
  ]
  %}
  
  {# Good. #}
  {%
  set story = [
    once,
    upon,
    aTime,
  ];
  %}
  
  {# Bad. #}
  {%
  set hero = {
      'firstName': 'Ada'
    , 'lastName': 'Lovelace'
    , 'birthYear': '1815'
    , 'superPower': 'computers'
  }
  %}
  
  {# Good. #}
  {%
  set hero = {
    'firstName': 'Ada',
    'lastName': 'Lovelace',
    'birthYear': '1815',
    'superPower': 'computers',
  %}

• 10.2 Additional trailing comma: Yes.

  Why? This leads to cleaner git diffs.

  {# Bad. Git diff. #}
  {%
  set hero = {
       'firstName': 'Florence',
  -    'lastName': 'Nightingale'
  +    'lastName': 'Nightingale',
  +    'inventorOf': ['coxcomb chart', 'modern nursing']
  }
  %}
  
  {# Good. Git diff. #}
  {%
  set hero = {
       'firstName': 'Florence',
       'lastName': 'Nightingale',
  +    'inventorOf': ['coxcomb chart', 'modern nursing'],
  }
  %}

  {# Bad. #}
  {%
  set hero = {
    firstName: 'Dana',
    lastName: 'Scully'
  }
  %}
  
  {%
  set heroes = [
    'Batman',
    'Superman'
  ]
  %}
  
  {# Good. #}
  {%
  set hero = {
    'firstName': 'Dana',
    'lastName': 'Scully',
  }
  %}
  
  {%
  set heroes = [
    'Batman',
    'Superman',
  ]
  %}

⬆ back to top

Naming Conventions

⬆ back to top

Resources

Tools

• Standalone Twig Linter

⬆ back to top

In the Wild

• Mediacurrent: Mediacurrent/twig-standards

⬆ back to top

Translation

We'd love to have it, so please submit a PR to add your fork in another language!

• American English: cybtachyon/twig-standards

Contributors

• View Contributors

⬆ back to top