Директивы Twig

  • 12.07.2026

Директивы Twig представляют собой специальные конструкции языка шаблонов Twig, которые управляют логикой отображения страницы. Они позволяют выполнять условия, циклы, подключать другие шаблоны, определять блоки, наследовать шаблоны, создавать переменные и выполнять другие операции непосредственно в шаблоне.

В отличие от выражений {{ ... }}, которые выводят данные, директивы записываются внутри тегов {% ... %} и обычно не выводят никакого текста самостоятельно. Их задача заключается в управлении процессом генерации HTML.

Например:

{% if user %}
    <p>Здравствуйте, {{ user.name }}!</p>
{% endif %}

Здесь директива if определяет, будет ли отображаться содержимое.

Чем директивы отличаются от выражений и комментариев

В Twig существует три основных типа конструкций.

Конструкция Назначение
{{ ... }} Вывод значения
{% ... %} Выполнение директив и управляющих конструкций
{# ... #} Комментарии

Например:

{# Комментарий #}

{% set title = "Главная" %}

<h1>{{ title }}</h1>

Основные директивы Twig

if

Директива if используется для условного отображения данных.

{% if user %}
    Привет, {{ user.name }}!
{% endif %}

Поддерживаются ветки elseif и else.

{% if age >= 18 %}
    Совершеннолетний
{% elseif age >= 14 %}
    Подросток
{% else %}
    Ребенок
{% endif %}

Условия могут использовать операторы сравнения и логические операторы.

{% if user and user.isAdmin %}
    Администратор
{% endif %}

for

Директива for предназначена для перебора массивов и других коллекций.

<ul>
{% for product in products %}
    <li>{{ product.name }}</li>
{% endfor %}
</ul>

Можно получать одновременно ключ и значение.

{% for key, value in data %}
    {{ key }}: {{ value }}
{% endfor %}

Если коллекция пустая, используется блок else.

{% for user in users %}
    {{ user.name }}
{% else %}
    Пользователи отсутствуют.
{% endfor %}

set

Создает новую переменную.

{% set title = "Новости" %}

Также можно сохранить результат блока.

{% set message %}
<strong>Добро пожаловать!</strong>
{% endset %}

Директивы для наследования шаблонов

Одной из сильных сторон Twig является поддержка наследования шаблонов.

extends

Определяет родительский шаблон.

{% extends "base.html.twig" %}

После этого текущий шаблон переопределяет необходимые блоки.

block

Создает именованный блок.

{% block content %}
    Содержимое страницы
{% endblock %}

В родительском шаблоне:

<!DOCTYPE html>
<html>
<body>

{% block content %}{% endblock %}

</body>
</html>

parent

Позволяет добавить содержимое родительского блока.

{% block stylesheets %}
    {{ parent() }}
    <link rel="stylesheet" href="/css/custom.css">
{% endblock %}

Подключение других шаблонов

include

Подключает другой шаблон.

{% include "header.html.twig" %}

Можно передавать собственные данные.

{% include "card.html.twig" with {
    title: article.title,
    text: article.text
} %}

Если файл отсутствует, можно избежать ошибки.

{% include "sidebar.html.twig" ignore missing %}

embed

Объединяет возможности include и extends.

{% embed "card.html.twig" %}

{% block body %}
    Текст статьи
{% endblock %}

{% endembed %}

Такой подход удобен при переопределении отдельных блоков внутри подключаемого шаблона.

Импорт макросов

import

Импортирует макросы.

{% import "forms.html.twig" as forms %}

Использование:

{{ forms.input("email") }}

from

Импортирует только необходимые макросы.

{% from "forms.html.twig" import input, textarea %}

Работа с пространствами имен

use

Импортирует блоки из другого шаблона.

{% use "blocks.html.twig" %}

Это удобно для повторного использования одинаковых блоков оформления.

Работа с автоматическим экранированием

autoescape

Позволяет изменить режим экранирования.

{% autoescape false %}
    {{ html }}
{% endautoescape %}

Использовать отключение экранирования следует только при полном доверии к данным. В противном случае появляется риск XSS-атак.

Работа с кэшированием и производительностью

В стандартном Twig отсутствует директива кэширования фрагментов шаблона. Однако некоторые CMS и фреймворки добавляют собственные расширения с директивами вроде cache.

В чистом Twig рекомендуется:

  • использовать наследование шаблонов;
  • избегать сложной бизнес-логики;
  • подготавливать данные в контроллере;
  • использовать кэш компилированных шаблонов.

Пространство имен шаблонов

При использовании Symfony часто встречается запись:

{% extends "@Admin/layout.html.twig" %}

Префикс @Admin обозначает пространство имен шаблонов, зарегистрированное в приложении.

Директива deprecated

Twig позволяет помечать шаблон как устаревший.

{% deprecated "Используйте profile.html.twig" %}

При использовании такого шаблона разработчик получит предупреждение.

Работа с несколькими переменными

Можно присвоить значения сразу нескольким переменным.

{% set first, second = "A", "B" %}

Использование циклов

Во время работы директивы for доступна специальная переменная loop.

{% for item in items %}
    {{ loop.index }}. {{ item }}
{% endfor %}

Полезные свойства объекта loop:

Свойство Описание
loop.index Номер элемента, начиная с 1
loop.index0 Номер элемента, начиная с 0
loop.revindex Номер элемента с конца
loop.first Первый элемент
loop.last Последний элемент
loop.length Размер коллекции

Пример:

{% for article in articles %}
    {% if loop.first %}
        <h2>Последние статьи</h2>
    {% endif %}

    {{ article.title }}
{% endfor %}

Лучшие практики использования директив Twig

При работе с Twig рекомендуется соблюдать несколько правил.

  • Используйте шаблоны только для представления данных.
  • Не размещайте бизнес-логику внутри шаблонов.
  • Подготавливайте данные в контроллере, сервисе или компоненте.
  • Используйте наследование шаблонов вместо копирования HTML.
  • Повторяющиеся элементы оформляйте через include, embed или макросы.
  • Не отключайте экранирование без необходимости.
  • Используйте понятные имена блоков и переменных.
  • Разбивайте большие шаблоны на небольшие переиспользуемые части.

Частые ошибки

Начинающие разработчики часто допускают следующие ошибки:

  • выполнение сложных вычислений внутри шаблона;
  • обращение к базе данных непосредственно из шаблона через пользовательские расширения;
  • дублирование одинаковой разметки вместо использования extends и include;
  • отключение автоматического экранирования без проверки источника данных;
  • использование большого количества вложенных условий, ухудшающих читаемость шаблона.

Заключение

Директивы Twig являются основным инструментом управления шаблонами. Они позволяют создавать условия, циклы, наследовать шаблоны, подключать повторно используемые части интерфейса, импортировать макросы и управлять экранированием данных. Правильное использование директив делает шаблоны компактными, безопасными и удобными для сопровождения. Особенно эффективно Twig раскрывает свои возможности в крупных проектах на Symfony, где наследование шаблонов, блоки и повторное использование компонентов помогают поддерживать единый стиль и упрощают развитие приложения.

Теги:
  • 12.07.2026