Twig для PHP: Полное руководство по шаблонизатору от Symfony

Twig — это современный, быстрый и безопасный шаблонизатор для языка PHP, разработанный командой Symfony. Он предоставляет разработчикам мощный, но при этом интуитивно понятный синтаксис для отделения логики представления (шаблонов) от бизнес-логики приложения. Twig решает ключевую проблему веб-разработки: смешивание PHP-кода с HTML, что приводит к "спагетти-коду" и снижает читаемость и поддерживаемость проекта.

Основная цель Twig — сделать шаблоны чистыми, безопасными и легко читаемыми. В отличие от чистого PHP, Twig ограничивает разработчика в выполнении произвольного кода внутри шаблона, что предотвращает типичные уязвимости, такие как XSS-атаки (Cross-Site Scripting), за счет автоматического экранирования вывода. Вместо сложных конструкций <?php foreach(...): ?> вы используете лаконичные {% for item in items %}, а вместо <?= $var ?> — {{ var }}. Это делает шаблоны доступными для верстальщиков и фронтенд-разработчиков, не знакомых с PHP.

Twig — это стандарт де-факто для фреймворка Symfony, но он также отлично интегрируется с Laravel (через пакет twigbridge), Drupal, WordPress и может использоваться как самостоятельная библиотека в любом PHP-проекте. Благодаря таким функциям, как наследование шаблонов, макросы, песочница (sandbox) и автоматическое экранирование, Twig является одним из самых популярных шаблонизаторов в экосистеме PHP.

Установка

Установка Twig осуществляется через менеджер зависимостей Composer. Убедитесь, что Composer установлен глобально.

composer require twig/twig:^3.0

После выполнения команды в вашем проекте появится папка vendor/ и файл composer.json с добавленной зависимостью. Для автозагрузки классов используйте стандартный файл vendor/autoload.php.

Быстрый старт: Минимальный рабочий пример

Создадим простейший шаблон и отобразим его. Структура проекта:

project/
├── templates/
│   └── hello.html.twig
├── vendor/
└── index.php

Шаблон: templates/hello.html.twig

<!DOCTYPE html>
<html>
<head>
    <title>Приветствие</title>
</head>
<body>
    <h1>Привет, {{ name }}!</h1>
    <p>Сегодня {{ "now"|date("d.m.Y") }}.</p>
</body>
</html>

PHP-скрипт: index.php

<?php
require_once 'vendor/autoload.php';

use Twig\Environment;
use Twig\Loader\FilesystemLoader;

// 1. Создаем загрузчик, который указывает на папку с шаблонами
$loader = new FilesystemLoader('templates');

// 2. Создаем окружение Twig
$twig = new Environment($loader, [
    'cache' => 'cache', // Путь для кэширования (рекомендуется)
    'auto_reload' => true, // Автоматически перезагружать при изменениях (для разработки)
]);

// 3. Рендерим шаблон, передавая переменные
echo $twig->render('hello.html.twig', ['name' => 'Мир']);
?>

Откройте index.php в браузере. Вы увидите страницу с заголовком "Привет, Мир!" и текущей датой.

Основные методы и функции Twig

Ниже приведены ключевые методы и конструкции, которые составляют основу работы с Twig.

1. Environment::render() — Рендеринг шаблона

Сигнатура: public function render(string $name, array $context = []): string

Описание: Основной метод для отображения шаблона. Принимает имя файла шаблона (относительно корня загрузчика) и ассоциативный массив переменных (контекст), которые будут доступны внутри шаблона.

<?php
// Внутри шаблона 'profile.html.twig' будут доступны переменные $user и $title
$html = $twig->render('profile.html.twig', [
    'user' => ['name' => 'Анна', 'age' => 30],
    'title' => 'Профиль пользователя'
]);
echo $html;
?>

2. Environment::addGlobal() — Глобальные переменные

Сигнатура: public function addGlobal(string $name, mixed $value): void

Описание: Позволяет добавить переменную, которая будет доступна во всех шаблонах, без необходимости передавать её в каждый вызов render(). Идеально подходит для данных, общих для всего сайта (например, текущий пользователь, название сайта).

<?php
$twig->addGlobal('site_name', 'Мой супер-сайт');
$twig->addGlobal('current_user', $user); // Объект пользователя

// Теперь в любом шаблоне можно использовать {{ site_name }}
?>

3. Environment::load() — Загрузка шаблона как объекта

Сигнатура: public function load(string $name): \Twig\TemplateWrapper

Описание: Загружает шаблон и возвращает объект TemplateWrapper. Это полезно, если вам нужно выполнить несколько операций с одним шаблоном (например, проверить блоки или отрендерить его несколько раз с разными данными).

<?php
$template = $twig->load('user_card.html.twig');

// Рендерим дважды с разными данными
echo $template->render(['user' => $user1]);
echo $template->render(['user' => $user2]);

// Проверяем, существует ли блок в шаблоне
if ($template->hasBlock('sidebar')) {
    // ...
}
?>

4. Environment::createTemplate() — Рендеринг строки как шаблона

Сигнатура: public function createTemplate(string $template): \Twig\TemplateWrapper

Описание: Позволяет интерпретировать произвольную строку как Twig-шаблон. Это мощный, но потенциально опасный метод, если строка поступает от пользователя. Используется для создания динамических шаблонов "на лету".

<?php
$templateString = '<h1>Здравствуйте, {{ name }}!</h1>';
$template = $twig->createTemplate($templateString);
echo $template->render(['name' => 'Ольга']);
// Выведет: <h1>Здравствуйте, Ольга!</h1>
?>

5. Environment::getLoader() и Environment::setLoader() — Управление загрузчиком

Сигнатура: public function getLoader(): \Twig\Loader\LoaderInterface и public function setLoader(\Twig\Loader\LoaderInterface $loader): void

Описание: Позволяют получить текущий загрузчик шаблонов или заменить его на другой. Это может быть полезно для реализации сложной логики загрузки (например, из базы данных или удаленного источника).

<?php
// Получаем текущий загрузчик
$currentLoader = $twig->getLoader();

// Создаем цепочку загрузчиков (сначала ищем в templates, потом в vendor/templates)
$chainLoader = new \Twig\Loader\ChainLoader([
    $currentLoader,
    new \Twig\Loader\FilesystemLoader('vendor/templates')
]);
$twig->setLoader($chainLoader);
?>

6. Environment::enableDebug() и Environment::disableDebug() — Режим отладки

Сигнатура: public function enableDebug(): void и public function disableDebug(): void

Описание: Включает или выключает режим отладки. Когда отладка включена, вы можете использовать расширение dump (аналог var_dump) внутри шаблонов. Никогда не включайте отладку на продакшене!

<?php
// Включение отладки (обычно в index.php для разработки)
if ($_ENV['APP_ENV'] === 'dev') {
    $twig->enableDebug();
}

// В шаблоне теперь можно использовать: {{ dump(user) }}
?>

7. Environment::setCache() — Настройка кэширования

Сигнатура: public function setCache(string|\Twig\Cache\CacheInterface $cache): void

Описание: Устанавливает путь к папке для кэширования скомпилированных шаблонов. Кэширование значительно ускоряет работу, так как Twig не будет парсить и компилировать шаблон при каждом запросе. Рекомендуется всегда включать кэш на продакшене.

<?php
// Устанавливаем папку для кэша
$twig->setCache('/path/to/cache/directory');

// Или передаем при создании Environment (как в быстром старте)
$twig = new Environment($loader, [
    'cache' => __DIR__ . '/cache',
]);
?>

8. Environment::registerUndefinedFilterCallback() — Обработка неопределенных фильтров

Сигнатура: public function registerUndefinedFilterCallback(callable $callable): void

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

<?php
$twig->registerUndefinedFilterCallback(function ($filterName) {
    // Если запрошен фильтр 'str_rot13', возвращаем встроенную функцию PHP
    if ($filterName === 'str_rot13') {
        return new \Twig\TwigFilter($filterName, 'str_rot13');
    }
    return null; // Или выбросить исключение
});

// В шаблоне: {{ "Hello"|str_rot13 }} выведет "Uryyb"
?>

9. Environment::registerUndefinedFunctionCallback() — Обработка неопределенных функций

Сигнатура: public function registerUndefinedFunctionCallback(callable $callable): void

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

<?php
$twig->registerUndefinedFunctionCallback(function ($functionName) {
    if ($functionName === 'random_int') {
        return new \Twig\TwigFunction($functionName, 'random_int');
    }
    return null;
});

// В шаблоне: {{ random_int(1, 10) }}
?>

10. Environment::addExtension() — Добавление расширения

Сигнатура: public function addExtension(\Twig\Extension\ExtensionInterface $extension): void

Описание: Регистрирует расширение (extension) в окружении Twig. Расширения — это основной способ добавления новых фильтров, функций, тегов и глобальных переменных. Например, расширение Twig\Extension\DebugExtension добавляет функцию dump.

<?php
// Добавляем расширение для отладки
$twig->addExtension(new \Twig\Extension\DebugExtension());

// Теперь в шаблоне доступна функция dump()
// {{ dump(variable) }}

// Пример создания своего расширения (упрощенно)
class MyExtension extends \Twig\Extension\AbstractExtension
{
    public function getFilters()
    {
        return [
            new \Twig\TwigFilter('price', function ($number) {
                return '$' . number_format($number, 2);
            }),
        ];
    }
}
$twig->addExtension(new MyExtension());
// В шаблоне: {{ 1234.5|price }} выведет "$1,234.50"
?>

Реальный практический пример: Система блога

Создадим небольшой, но функциональный пример: вывод списка статей блога с использованием наследования шаблонов (одна из сильнейших сторон Twig).

Структура проекта:

blog/
├── templates/
│   ├── base.html.twig      (Базовый шаблон)
│   └── blog/
│       └── index.html.twig (Шаблон для списка статей)
├── cache/
├── index.php
└── vendor/

1. Базовый шаблон: templates/base.html.twig

<