Twig в Symfony: рабочие приёмы для шаблонов

Шаблон должен собрать готовые данные в HTML — и всё. Но в реальном проекте на Symfony 7.x Twig-файл быстро обрастает вызовами методов сущностей, фильтрацией коллекций и запросами к базе прямо из {% for %}. Страница начинает делать по сорок SQL-запросов, а найти, где именно, невозможно: логика размазана по десятку include. Разбираем, где в шаблоне проходит граница ответственности, чем платит каждый способ переиспользования разметки и как не превратить шаблон в контроллер.

Задача: карточка товара с блоками, которые повторяются

Возьмём типичный случай — страница товара, где повторяются блок цены, блок рейтинга и кнопка «в корзину». Их же надо показать в списке товаров и в блоке «похожие». Очевидное решение — скопировать разметку. Через месяц дизайн цены меняется, и вы правите её в пяти файлах, забыв про шестой.

Второе очевидное решение — вынести всё в один большой include и передавать туда объект товара целиком. Тоже ловушка: внутри такого include легко написать {{ product.reviews|length }}, а если reviews — ленивая коллекция Doctrine, Twig дёрнет отдельный запрос на каждый товар в списке. Тридцать товаров — тридцать запросов, и вы этого не увидите, пока не откроете профайлер.

Три способа переиспользовать разметку

В Twig есть три механизма, и они не взаимозаменяемы. Разница — в изоляции области видимости и в том, кто готовит данные.

• include — вставляет другой шаблон. По умолчанию видит все переменные родителя, что и создаёт скрытые запросы. Изоляцию включают явно.
• embed — тот же include, но с возможностью переопределять блоки внутри вставляемого шаблона. Нужен, когда переиспользуемый кусок имеет «дырки» под контент.
• компонент (пакет symfonycasts/twig-component) — шаблон со своим PHP-классом, который сам готовит данные. Логика уезжает из Twig в класс.

include с явной изоляцией

Самый частый источник лишних запросов — include, который наследует контекст родителя. Передавайте только то, что нужно, и добавляйте only:

{# Symfony 7.x, Twig 3.x #}
{# price.html.twig ждёт ровно две переменные и ничего больше не видит #}
{{ include('product/_price.html.twig', {
    amount: product.price,
    currency: 'RUB'
}, with_context = false) }}

Флаг with_context = false (или короткая форма only) отрезает шаблону доступ к родительским переменным. Теперь внутри _price.html.twig нельзя случайно написать {{ product.reviews }} — переменной product там просто нет. Это защита от ленивых запросов на уровне разметки.

Если во include вы передаёте объект сущности целиком «на всякий случай» — вы отдаёте шаблону право делать запросы к базе, о которых не знаете. Передавайте примитивы и заранее посчитанные значения.

embed, когда нужны дырки под контент

Карточка с рамкой, заголовком и произвольным телом — классический случай для embed. В обычный include контент «сверху» не передашь, а embed позволяет переопределить блоки вставляемого шаблона:

{# _card.html.twig #}

    
{% block head %}{% endblock %}
    
{% block body %}{% endblock %}


{# использование #}
{% embed 'ui/_card.html.twig' %}
    {% block head %}Похожие товары{% endblock %}
    {% block body %}
        {% for item in similar %}
            {{ include('product/_price.html.twig', { amount: item.price, currency: 'RUB' }, only) }}
        {% endfor %}
    {% endblock %}
{% endembed %}

Компонент, когда есть логика подготовки

Если для блока надо посчитать скидку, отформатировать статус или подтянуть связанные данные — это не работа шаблона. Twig-компонент выносит подготовку в PHP-класс, а шаблон остаётся тонким:

amount / 100, 2, ',', ' ');
    }
}

{# templates/components/ProductPrice.html.twig #}
{{ this.formatted }} {{ currency }}

Вызов в шаблоне становится декларативным:

Синтаксис <twig:ComponentName /> появился в Twig Component 2.x. Точную минимальную версию пакета сверьте в его документации — в старых релизах вызов был через функцию component().

Когда что выбирать

Простое правило: пока блоку не нужно ничего вычислять — хватит include с only. Как только в шаблоне появляется if с бизнес-условием или форматирование — переносите в компонент или в контроллер.

Что ломается на практике

Три ошибки, которые встречаются чаще всего.

• Ленивые запросы из шаблона. {{ product.reviews|length }} в цикле по списку — это N запросов. Считайте количество в репозитории через отдельный запрос с COUNT и передавайте число, а не коллекцию.
• Логика в Twig. Тернарники в тернарниках, {% set %} с вычислениями, фильтрация коллекций через |filter с замыканием. Всё это не покрывается юнит-тестами и не находится грепом. Переносите в контроллер или компонент.
• include без only. Работает, пока родитель случайно содержит переменную с нужным именем. При рефакторинге родителя include молча получает другое значение или null.

Как найти лишние запросы

Symfony Profiler в dev-режиме показывает вкладку Doctrine с числом запросов на страницу и вкладку Twig с деревом отрендеренных шаблонов. Если число запросов растёт линейно с числом элементов в списке — ищите обращение к ленивой связи внутри цикла. Чините на уровне запроса в репозитории (JOIN или отдельный агрегат), а не в шаблоне.

Что делать дальше

Пройдите по шаблонам грепом на include( без only и добавьте изоляцию везде, где передаёте объекты. Откройте профайлер на самых тяжёлых страницах и посмотрите число SQL-запросов — всё, что растёт с длиной списка, лечится на уровне репозитория. Для блоков с логикой подключите symfonycasts/twig-component и переносите подготовку данных в классы. Автоэкранирование включено по умолчанию — не отключайте его глобально; если нужен сырой HTML, используйте |raw точечно и только для проверенных данных.