Twig Introduction

Introduction

Twig is a modern template engine for PHP.

Twig lets you separate business logic from presentation logic by using template files that are a mix of HTML and basic code constructs offered by the Twig language.

Here's an example of a small, very basic Twig template. A backend developer has made the first_name variable available to the template. The front-end developer does not need to figure out how to write PHP and communicate with the backend to retrieve the user's first name.

<h1>Hello {{ first_name }}</h1>
<p>Welcome back!</p>

Tip: you can use our Twig Playground to experiment! 

Notice that this template does not contain any PHP code: using PHP code inside Twig templates is not allowed.

Since no PHP is allowed in Twig templates, Twig itself provides a small number of programming language concepts such as:

• Variables
• Loops (iterations)
• If/then/else statements (selections)
• Arrays and Objects that represent data
• Predefined functions and filters
• Operators for comparison, containment, logic, math, and tests

Twig's ultimate goal is to let front-end developers write front-end code without necessarily knowing PHP or understanding the complexity of the back-end they are working with. 

In a nutshell: back-end developers provide the data; front-end developers provide the designed, themed output to the end user.

How does Twig work?

Systems like Drupal that use Twig for their templates generally go through the following steps:

• System (Drupal, Symphony application, ...) gathers data it wants to display.
• System tells Twig Engine to compile one or more Twig template files into HTML, and passes along the required data (variables, also called parameters sometimes).
• Twig compiles the template(s), substituting the template's variables with the data it receives and executing any programming logic (expressions) it encounters.
• Twig sends the compiled bits HTML back to the System.
• System merges the compiled HTML bits into a complete HTML document and sends that back to the browser for display.

Note: this is a slightly simplified description of how Twig compiles templates into HTML. In reality there is an intermediary step where Twig first compiles templates into PHP, and then executes that PHP to get to the end result: HTML. This is only relevant for advanced use cases or to troubleshoot bugs in the Twig engine. If you're just now learning Twig you can forget about this intermediary compilation step.

Delimiter types

Twig provides three sets of delimiters:

• Twig variable expression delimiters: {{ }}
• Twig code blocks: {% %}
• Twig comment delimiters: {# #}

All of your Twig syntax must be contained inside one of these three types of delimiters. Any Twig code that is not contained inside these delimiters will be considered as plain text, and will be rendered (printed) as such.

Twig Variable expression delimiters

To print the value of a variable, use the {{ }} delimiters:

<h1>Hello {{ first_name }}</h1>
<p>Welcome back!</p>

When this template is rendered, {{ first_name }} will be replaced by the value provided by the first_name variable.

Twig Code blocks

Template logic such as variable assignments, if-then-else conditions, and loops must be contained within {% %} delimiters:

<h1>Hello {{ first_name }}</h1>
{% if user_is_new == true %}
<p>Great to have you on board!</p>
{% else %}
<p>Welcome back.</p>
{% endif %}

This template prints one of two messages, depending on whether the user is new or not. It expects two variables:

• first_name
• user_is_new

The Twig Tags used in this template:

• {% if %}
• {% else %}
• {% endif %}

Twig Comment delimiters

Comments in your Twig code are ignored by the compiler, and will not be part of the end result - the rendered template.

To add comments to your Twig template, use the {# #} delimiters:

Example 1 - single line comment

{# Welcome message template. #}
<h1>Hello {{ first_name }}</h1>
<p>Welcome back!</p>

Example 2 - multi-line comment

{#
Welcome message template.
Available variables:
 - first_name (string)
 - user_is_new (boolean)
# }
<h1>Hello {{ first_name }}</h1>
{% if user_is_new == true %}
<p>Great to have you on board!</p>
{% else %}
<p>Welcome back.</p>
{% endif %}