Как редактировать файл twig

Обновлено: 05.07.2024

Twig – это современный дружественный шаблонизатор, разработанный для PHP. Будучи более эффективным шаблонным движком, он является отличной альтернативой PHPTemplate при разработке веб-приложения. Его синтаксис очень прост для понимания. Кроме того, Twig устраняет необходимость выполнения лишних динамических PHP-операций в файлах шаблона.

Данное руководство продемонстрирует, как установить Twig на виртуальный выделенный сервер и начать работу с ним.

Примечание: предполагается уже настроенного облачного сервера (предпочтительно Linux). Кроме того, нужно установить LAMP stack (хотя база данных для выполнения руководства не нужна). Для корректной работы Twig также требуется PHP 5.2.4+.

Зачем нужен Twig?

Зачем нужны шаблонизаторы в целом? Все очень просто: для разделения задач. Чтобы рассмотреть этот вопрос на примерах, создайте папку проекта в root-каталоге веб-сервера (/var/www) и назовите его twig:

cd /var/www
mkdir twig
cd twig

Теперь создайте еще пару папок для этого небольшого тестового приложения: одну для PHP-файлов, вторую – для шаблонов Twig соответственно:

mkdir app
mkdir views

В папке app создайте одноименный php-файл.

Так почему бы не использовать этот формат постоянно? Дело в том, что такой PHP-файл может стать гораздо больше и сложнее (что происходит в большинстве случаев), а это повлечет большие проблемы с разработкой макета сайта. Кроме того, тег Н1 был закодирован в непосредственно в echo, что также не лучший вариант работы.

Если над проектом совместно с разработчиком будет работать дизайнер, то ему придется рыться в этом файле, а этого желательно не допускать.

Таким образом, выходом из сложившейся ситуации является разделение презентации (макета) и логики (программирования) проекта; лучший способ сделать это – использовать механизм шаблонов (например, Twig).

Созданное только что приложение еще понадобится после установки Twig.

Установка Twig

Рекомендуется устанавливать Twig через Composer, инструмент управления зависимостями PHP. За информацией об этом инструменте можно обратиться к руководству «Установка и использование Composer».

Скачайте инсталлятор Composer в root-папку приложения (twig):

Это загрузит файл по имени composer.phar, который является исполняемым файлом Composer. Затем создайте файл с названием composer.json:

И внесите в него следующий код:

Благодаря этому коду приложение будет зависить от движка шаблонов Twig. Теперь давайте использовать команду composer, чтобы установить зависимости:

php composer.phar install

Теперь файлы Twig загружены в папку vendor/Twig. Если добавить других зависимостей, они также будут установлены в папке vendor.

Теперь нужно «подключить» этот файл к приложению. Опять же, можно использовать функцию автозагрузчика Composer, чтобы загрузить все установленные зависимости. Откройте файл app.php:

Удалите все его содержимое и внесите эту строку:

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

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

require_once '/path/to/lib/Twig/Autoloader.php';
Twig_Autoloader::register();

При использовании Composer в этом нет необходимости.

Под командой require нужно поместить файл шаблона Twig и задать переменную, которую нужно вывести на страницу. Вставьте следующий код:

<?php $loader = new Twig_Loader_Filesystem('../views/'); ?>
<?php $twig = new Twig_Environment($loader); ?>
<?php echo $twig->render('page.html', array('text' => 'Hello world!')); ?>

Во-первых, это создаст объект загрузчика, которому передается путь к папке, содержащей файлы шаблонов (пустая на данный момент папка views была создана ранее). Кроме того, этот код также создаст объект среды, в котором хранится конфигурация. В завершение, строка render объекта среды загружает файл шаблона, заданный в качестве первого аргумента и визуализирует его с учетом переменных, заданных в качестве второго аргумента. Теперь нужно создать файл page.html, в который можно внести переменные, содержащие текст, который нужно отобразить.

В него внесите следующее:

Если сохранить этот файл и перезапустить файл app.php в браузере, на страницу будет выведен текст, взятый в теги Н1. Теперь, создав этот файл, можете поэкспериментировать с ним. Переменные, заданные через функцию render, теперь можно вносить в фигурные скобки.

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

Итоги

Это руководство продемонстрировало установку Twig через Composer, а также вывод на экран простых переменных с помощью отдельных файлов шаблонов. Следующее руководство этой серии более подробно рассматривает использование синтаксиса Twig для разработки файлов шаблонов.

Русскоязычная документация по Twig - PHP шаблонизатору. Руководство по Твиг на русском языке

Этот документ описывает синтаксис и семантику шаблона и будет наиболее полезен для тех, кто создает шаблоны TWIG.

Краткий обзор

Шаблон - это просто текстовый файл. Он может генерировать любой текстовый формат (HTML, XML, CSV, Latex, и т.д.). Он не обязан иметь особого расширения, .html, или .xml расширения подойдут.

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

Ниже приводится минимальный шаблон, который иллюстрирует основы. Мы рассмотрим детали позже:

Есть два вида разделителей: И >. Первый из них используется для выполнения операторов, таких как for-циклы , последний печатает результат выражения в шаблон.

Интеграция со средами разработки.

Многие среды разработки поддерживают подсветку синтаксиса и автодополнение для TWIG.

Textmate с помощью Twig bundle
Vim с помощью Jinja syntax plugin или vim-twig plugin
Netbeans с помощью Twig syntax plugin (до версии 7.1, нативно , начиная с версии 7.2)
PhpStorm (нативно , начиная с версии 2.1)
Eclipse с помощью Twig plugin
Sublime Text с помощью Twig bundle
GtkSourceView с помощью Twig language definition (используется в gedit и других проектах)
Coda иSubEthaEdit с помощью Twig syntax mode
Coda 2 с помощью other Twig syntax mode
Komodo и Komodo Edit с помощью Twig highlight/syntax check mode
Notepad++ с помощью Notepad++ Twig Highlighter
Emacs с помощью web-mode.el

Переменные

Приложение передает переменные, с которыми вы можете работать в шаблоне. Переменные могут иметь атрибуты или элементы, к которым вы можете иметь доступ. Как выглядит переменная определяется приложением, которое ее предоставило. Вы можете использовать точку (.) чтобы получить доступ к атрибутам переменной (методы или свойства PHP-объекта или элементы PHP- массива), или так называемый индекс ([]):

Когда атрибут содержит специальные символы (такие как - что будет интерпретировано как оператор вычитания ), используйте функцию attribute вместо доступа к атрибуту переменной.

Важно знать,что фигурные скобки не являются переменной, а печатают предложение.
Если вы хотите получить доступ к переменным внутри тегов, не ставьте скобки.

Если переменная или атрибут не существует, вы получите значение null , когда опция strict_variables установлена false, в обратном случае Twig выбросит ошибку.

Реализация

Для удобства foo.bar делает следующие вещи на уровне PHP:

проверяет является ли foo массивом и bar верным выражением;
если нет, и foo является объектом, проверяется что bar является допустимым свойством
если нет, и foo является объектом, проверяется что bar является допустимым методом (даже если bar является конструктором - используйте use__construct() вместо этого)
если нет, и foo является объектом, проверяется что getBar является допустимым методом
если нет, и foo является объектом, проверяется что isBar является допустимым методом
если нет, то возвращает значение null

С другой стороны, foo['bar'] работает только с массивами PHP:

проверяется, является ли foo массивом и bar допустимым элементом
если нет , то возвращает значение null

Если вы хотите получить динамический атрибут для переменной, используйте функцию attribute вместо этого.

Глобальные переменные

Следующие переменные всегда доступны в шаблонах:

_self : ссылается на текущий шаблон;
_context : ссылается на текущий контекст;
_charset : ссылается на текущую кодировку.

Присвоение переменных

Вы можете придать значения переменных внутри блоков кода. Присвоения используют тег set :

Фильтры

Переменные могут быть изменены с помощью фильтров filters. Фильтры отделяются от переменных с помощью pipe-символа (|) и могут иметь дополнительные аргументы в скобках. Можно объединять несколько фильтров. Выход одного фильтра направляется в следующий.

Следующий пример удаляет все HTML-теги и title из name:

Фильтры, которые принимают аргументы,имеют круглые скобки вокруг аргументов. Этот пример присоединит список, разделенный запятой.

Чтобы применить фильтр для секции в коде, оберните его с тегом filter:

Чтобы узнать больше о встроенных фильтрах зайдите на страницу filters.

Функции

Можно вызывать функции чтобы генерировать контент. Функции могут быть вызваны по имени со скобками после него и могут иметь аргументы.

Например, функция range возвращает список, содержащий арифметическую прогрессию целых чисел:

Чтобы узнать больше о встроенных функциях зайдите на страницу functions.

Именованные аргументы

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

Именованные аргументы также позволяют пропустить некоторые аргументы, для которых вы не хотите изменять значение по умолчанию:

Вы также можете использовать позиционные и именованные аргументы в одном вызове, и в этом случае позиционные аргументы должны идти впереди именованных аргументов.

Каждая страница документации по функциям и фильтрам имеет раздел, где имена всех аргументов выписаны, если они поддерживаются.

Управляющая структура

Управляющая структура относится к тем вещам, которые управляют программой - условия (i.e. if/elseif/else), for-циклы и блоки. Управляющая структура появляется внутри блоков .

Например, чтобы показать список всех пользователей, которые записаны в переменной users , используйте тег for:

Тег if можно использовать чтобы проверить выражение:

Чтобы узнать больше о встроенных тегах зайдите на страницу tags.

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

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

Тэг include используется для включения шаблона и включению использованного контента к текущему:

По умолчанию включенные шаблоны передаются в текущий контекст.

Контекст, который передается во включенный шаблон включает переменные, определенные в шаблоне:

Включенный шаблон render_box.html может получить доступ к box.

Имя файла шаблона зависит от загрузчика шаблона. Например, Twig_Loader_Filesystem позволяет получить доступ к другим шаблонам по имени. Вы можете включить шаблоны в ниже лежащих директориях используя знак слэша:

Это поведение зависит от приложения, в которое встраивается Twig.

Наследование шаблонов

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

Звучит сложно, но на самом деле все очень просто. Это легко понять с помощью следующего примера.

Давайте определим базовый шаблон, base.html, который определяет простой HTML скелетный документ, который вы можете использовать для простой страницы с двумя колонками:

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

Шаблон-потомок может выглядеть так:

Тег extends очень важен здесь. Он говорит механизму шаблонов, что этот шаблон "расширяет" другой шаблон. Когда система шаблонов вычисляет этот шаблон, сначала он ищет родителя. Тег extends должен быть первым тегом в шаблоне. Следует заметить, что так как шаблон-ребенок не определяет блок footer , используется значение из родительского шаблона.

Возможно передать содержание родительского шаблона используя функцию parent.

Это дает результаты родительского блока:

Экранирование HTML

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

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

Автоматическое сохранение поддерживается только если расширение escaper включено (что так и есть по умолчанию).

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

Если сохранение вручную включено, это ваша обязанность сохранить все переменные если это нужно. Что нужно сохранить? Все переменные, которым вы не доверяете.

Сохранение работает , если пропустить переменную через escape или e фильтр:

По умолчанию, фильтр escape использует html метод, но в зависимости от сохраняемого контекста, вы возможно захотите использовать другие методы:

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

Вне зависимости от того, включено ли автоматическое сохранение или нет, вы можете выделить секцию шаблона, которую нужно или не нужно сохранить, используя тег autoescape:

По умолчанию, авто-сохранение сохраняет html. Если выводить переменные в других контекстах, нужно явно сохранить их, используя подходящий метод:

Экранирование

Иногда желательно или даже необходимо заставить Twig игнорировать те части, которые в противном случае он воспримет как переменные или как блоки.

Самым простым способом для вывода переменной разделитель

Макросы

поддержка значений аргументов была добавлена по умолчанию в Twig 1.12.

Макросы сравнимы с функциями в обычных языках программирования. Они полезны для повторного использования часто используемых HTML - фрагментов чтобы не повторять себя. Макрос определяется через macro теги. Вот небольшой пример (впоследствии называемый forms.html) макроса, который представлен в виде элемента формы:

Макрос может быть определен в любом шаблоне, и должен быть "импортирован" через тег import до использования:

Кроме того, вы можете импортировать отдельные имена макросов из шаблона в текущее пространство имен с помощью тега from или дать им имя:

По умолчанию значение также может быть определено для макро аргументов прямо в вызове макроса:

Выражения

Twig позволяет выражения везде. Такая работа очень похожа на обычный PHP и даже если вы не работаете с PHP, вы почувствуете себя с ним комфортно.

Литеры

Самой простой формой выражений являются литералы. Литералы представлены для таких типов PHP, как строки, числа и массивы. Существуют следующие литералы:

"Hello World" : Все между двумя двойными или одинарными кавычками является строкой. Они полезны, когда вам нужна строка в шаблоне (например, как аргументы функций,фильтры или для того чтобы просто расширить или включить шаблон). Строка может содержать разделитель, если ему предшествует обратный слеш () -- как в 'It's good'
42 / 42,23 : Целые числа и числа с плавающей точкой создаются написанием чисел . Если точка есть в числе то это float, в противном случае integer.
["foo", "bar"] : Массивы определяются последовательностью выражений, разделенных запятыми (,) и окруженных квадратными скобками ([]).
: Хэши определяется списком ключей и значений, разделенных запятыми (,) и взятых в фигурные скобки (<>):

true/false : true представляет истинное значение, false представляет ложное значение.
null : null не представляет никакого определенного значения. Это значение возвращается, когда переменной не существует. none является синонимом null.

Массивы и хэши могут быть вложенными:

Использование двойных кавычек или одиночных кавычек не имеет никакого ьвлияния на производительность, но строки интерполяции поддерживается только для строк в двойных кавычках.

Вычисления

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

+ : Добавляет два объекта вместе (операнды преобразованы в числа). > равно 2.
- : Вычитает второе число из первого. > равно 1.
/ : Деление двух чисел. Возвращенное значение будет числом с плавающей точкой. > есть 0,5.
% : Вычисляет остаток от целочисленного деления. > есть 4.
// : Деление двух чисел и возвращает (в виде дроби) целый результат. > = 2 , > является -3
* : Умножает левый операнд на правый. > возвратится 4.
** : Генерирует левый операнд в степень правого операнда. > возвратится 8.

Логика

Вы можете объединить несколько выражений со следующими операторами:

and : Возвращает истину, если левый и правый операнды оба истинны.
or : Возвращает истину, если левый или правый операнд истинны.
not : Отрицает выражение.
(expr) : Групипровка вырожений.

Twig также поддерживает побитовые операторы (b-and, b-xor, and b-or).

Сравнения

Следующие операторы сравнения поддерживаются в любом выражении: == , != , < , > , >= и <= .

Вы также можете проверить, если строка начинается или заканчивается другой строкой:

Для сложных сравнений строк, оператор matches позволяет вам использовать регулярные вырожения:

Оператор in

Оператор in осуществляет проверку содержания.

Он возвращает true если левый операнд содержится в правом:

Вы можете использовать этот фильтр, чтобы выполнить проверку на содержание со строками, массивами или объектами, осуществляющих Traversable интерфейс.

Чтобы выполнить проверку на то, что левый операнд не содержится в правом, нужно использовать not in оператор.

Операторы проверки

Оператор is выполняет тесты. Тесты могут быть использованы для тестирования переменной в отношении общего выражения. Правый операнд является именем теста:

Тесты также используют аргументы:

Тесты могут быть инвертированы при использовании is not оператора:

Перейдите на страницу tests чтобы узнать больше о встроенных тестах.

Другие операторы

Поддержка расширенного тройного оператора была добавлена в Twig 1.12.0.

Следующие операторы очень полезны, но не вписываются ни в какую из категорий:

.. : Создает последовательность, основанную на операнде до и после оператора.
| : Применяет фильтр.

Строка интерполяции

Строка интерполяции была добавлена в Twig 1.5.

Управление пробелами

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

Вы также можете контролировать пробелы на уровне тегов. Используя модификаторы управления пробелами в ваших тегах, вы можете обрезать начальные и / или конечные пробелы.

Twig поддерживает два модификатора:

Обрезка пробелов с помощью модификатора - : удаляет все пробелы (включая переводы строк);
Обрезка пробелов строк с помощью модификатора

Модификаторы можно использовать с любой стороны тегов, например, и они занимают все пробелы для этой стороны тега. Можно использовать модификаторы на одной стороне тега или на обеих сторонах:

В дополнение к модификаторам пробелов, Twig также имеет фильтр spaceless , который удаляет пробелы между тегами HTML:

Метка apply была введена в Twig 2.9; используйте тег filter с предыдущими версиями.

Расширения

Twig может быть легко расширен.

Если вы ищете новые теги, фильтры или функции, посмотрите это в официальном хранилище расширений Twig extension repository.

Если вы хотите создать свой собственный, прочтите главу Creating an Extension.

Зачем нужны шаблонизаторы?

Создание качественного продукта, будь то сайт или приложение — результат сплоченной работы целой команды. Это программисты, верстальщики, дизайнеры. Чем сложнее проект, тем важнее отделить его логику от представления. Только при успешном их разделении backend и frontend-разработчики смогут эффективно сотрудничать. Всего этого можно достигнуть благодаря шаблонизаторам.

На данный момент существует множество способов генерации конечных html-страниц. В том числе большое количество шаблонизаторов. Вот некоторые из них: Blade, Smarty, Twig, Volt. Мы остановимся подробнее на Twig.

История создания

Twig был написан в 2008 году австрийским разработчиком Армином Ронахером, как обработчик шаблонов с открытым исходном кодом, созданный на языке программирования php. Вскоре он занялся разработкой на Python и больше не возвращался к шаблонизатору. Однако труды были не напрасны. Идею Twig поддержал и развил ведущий разработчик фреймворка Symfony - Фабьен Потенсье.

Поколдовав над кодом и написав всю необходимую документацию, он пришел к выводу, что код вполне целостен и библиотеку можно показать публично. В своём личном блоге Фабьен отметил: «Twig не только один из самых функциональных шаблонизаторов, но и самый быстрый».

Особенности Twig

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

высокая скорость работы

наследование шаблонов (возможность определить базовый и дочерние шаблоны)

понятный и компактный синтаксис

оптимизированный php код

безопасный режим «песочницы» (пользователи имеют ограниченный набор тегов, фильтров и методов объектов, определенных разработчиком )

возможность создания и использования макросов

полностью документирован (и API тоже)

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

Один из самых простых способов установки — скачать компонент с GitHub. Далее следует распаковать архив и каталог lib поместить в папку с рабочим проектом.

Всё необходимое для того, чтобы подключить Twig находится в файле index.php. В каталоге templates размещены файлы шаблонов. В нашем случае base.html и books.html. compilation_cache используется для хранения php-файлов, созданных шаблонизатором для работы.

1. Подключаем Twig.

2. Сообщаем шаблонизатору местонахождение шаблонов. В качестве аргумента передаем путь к папке templates.

3. Создаем объект шаблонизатора, указав необходимые опции cache и auto_reload.

Параметру cache передается путь к папке compilation_cache.

Вторую опцию активируем, прописав true. Это необходимо при обновлении страницы, чтобы Twig заново обработал шаблон. В противном случае шаблонизатор закеширует страницы. В будущем, после завершения работы над сайтом, данную опцию можно отключить.

4. Для наглядной работы с шаблонизатором сформируем небольшой массив со списком книг вида ключ-значение.

5. Используем метод render() для передачи данных в шаблон и вывода html результата.

Аргументы: название файла шаблона и созданный ранее массив.

Общий вид файла:

6. Настройка base.html (базовый шаблон)

Наследование шаблонов позволяет вынести общие элементы сайта, такие как header, footer, sidebar в базовый шаблон. Он определяет костяк html-документа. Каждый блок, в свою очередь, может быть переопределен дочерним шаблоном.

В нашем примере два блока: title и content.

7. Настройка books.html (дочерний шаблон)

a) указываем родительский шаблон

б) вписываем название дочерней страницы в наш блок title. Оно появится между тегам title в base.html

в) заполняем содержание, оно будет помещено в блок content базового шаблона

Цикл for проходится по данным, которые были переданы в шаблон посредством метода render(). Для извлечения значений необходимо обратиться к элементам по их ключам. В нашем случае это: > и > .

Выстраивается следующая цепочка:

Срабатывает метод $twig->render('books.html', array('books' => $books))

Twig подгружает шаблон books.html и формирует html-содержание

Распознает, что books.html это дочерний шаблон base.html и помещает туда сформированное содержание

Шаблонизатор возвращает полноценную страницу html

Оформление кода

Правило 2. Не ставить пробелов:

после открытия круглой скобки и перед закрытием круглой скобки в выражениях

перед и после разделителей строк

перед и после следующих операторов: |, ., . []

перед и после круглой скобки, используемой для фильтра и вызовов функций

перед и после открытия и закрытия массивов и хэшей

Правило 3. В названиях переменных использовать маленькие буквы и символы подчеркивания.

Правило 4. Делать отступы внутри тегов.

Циклы и условия в Twig

В Twig есть такие базовые конструкции как циклы и условия. В примере с выводом книг был задействован цикл for:

Одной из особенностей шаблонизатора является использование оператора двоеточие (..). Это альтернатива range в php для создания массива, содержащего диапазон элементов.

Пример перебора цифр:

То же самое можно проделать с буквами.

Кроме того, полезной является возможность добавить условие в определение цикла.

Пример - фильтрация продуктов по цене:

Условия, поддерживаемые Twig: if, elseif, if not и else:

Фильтры в Twig

Фильтры – более продвинутые средства Twig. Эти инструменты позволяют форматировать данные перед выводом, определять в каком формате и как будет передана информация в шаблон. Вот несколько из них:

Date и date_modify - форматируют и модифицируют дату

Format - преобразует placeholder’ы, строки, которые начинаются со знака %, заменяя на подставляемые значения.

Striptags - удаляет html теги, все пробелы, находящиеся рядом, заменяет одним.

Escape - экранирует строку для безопасного отображения.

Заключение

Twig – это мощное средство для создания шаблонов сайта, которое хорошо документировано и полностью протестировано. Он особенно полезен для командного ведения проекта, позволяя комфортно работать программистам и frontend-разработчикам.

Open with Desktop
View raw
Copy raw contents Copy raw contents Loading

Copy raw contents

Текущая глава описывает синтакс и семантику шаблонизатора Twig и будет наиболее полезна в качестве справочника тем, кто занимается разработкой шаблонов.

Краткий обзор

Шаблон представляет собой обычный текстовый файл. Шаблонизатор поддерживает любой текстовый формат - XHTML, XML, CSV, LaTeX и др. Определенные требования к расширению файла отсутствуют, он может быть как с расширением .html , так и с .xml - оба варианта подойдут.

Шаблон содержит переменные и выражения, которые во время анализа заменяются на соответствующие значения. Так же в шаблоне могут присутствовать теги , которые влияют на логику выполнения (обработки) шаблона.

Ниже представлен минимальный пример шаблона, который позволит наглядно продемонстрировать некоторые основы:

Существует три вида разделителей:

: предназначен для выполнения команд, например, присвоения ( set ) или циклов.
> : предназначен для вывода значений в шаблон.
: предназначен для комментариев.

Интеграции с IDE

Большинство современных редакторов кода поддерживают подсветку синтаксиса и автодополнения Twig.

Textmate через Twig bundle
Netbeans через Twig syntax plugin
PhpStorm (встроенная поддержка)
Visual Studio Code через Twig pack.

Полезный сервис - TwigFiddle, который позволит выполнить и изучить результат работы шаблонизатора прямо в браузере.

Переменные

Приложение передаёт переменные в шаблон для управления логикой отображения и самим отображением. Переменные могут содержать аттрибуты и свойства (элементы) к которым вы можете получить доступ прямо из шаблона. То, как будет выглядеть переменная в шаблона сильно зависит от используемого приложения и того, как само приложение передаёт / описывает передаваемые переменные.

Для доступа к аттрибутам переменной (методам, свойствам PHP объектов или массивам) можно воспользоваться символом точки - . , или так называемым "индексным доступом" - [] .

В случае, если аттрибут содержит специальные символы, например, знак минуса - , то необходимо воспользоваться функцией attribute , вместо использования . :

Пояснение: использование символа - и доступа к аттрибуту через . приводит к некорректному интерпретированию выражения:

Анализатор воспримет foo.data как одну переменну, из значения которой вычитают значение другой переменной - bar .

Если переменная или свойство не существует, то результатирующим значением будет значение null при отключенном режиме strict_variables (равен false ). В случае активированного режима strict_variables (равен true ) Twig выбросит исключение (см. настройки окружения).

Реализация: Ради удобства использования foo.bar , осуществляются следующие проверки на уровне PHP:

проверка, что foo это массив, а bar действительный элемент;
если нет, то проверка того, что foo это объект, а bar действительное свойство;
если нет, то проверка того, что foo это объект, а bar действительный метод;
если нет, то проверка того, что foo это объект, а getBar действительный метод;
если нет, то проверка того, что foo это объект, а isBar действительный метод;
если нет, то проверка того, что foo это объект, а hasBar действительный метод;
если нет, то вернуть значение null .

В то же время foo["bar"] работает только с PHP-массивами:

проверка, что foo это массив и bar действительный элемент;
если нет, то вернуть значение null .

Если есть необходимость обращения к динамическим аттрибутам, то рекомендуется использовать функцию attribute .

Глобальные переменные

Следующие переменные всегда доступны в шаблонах:

_self : ссылается на текущее название шаблона.
_context : ссылается на текущий контекст.
_charset : ссылается на текущую кодировку.

Присваивание значений переменным

Присваивать значения переменным можно в блоках использую тег set :

Фильтры

Переменные могут быть изменены фильтрами. Фильтры отделяются от переменных символом | (pipe symbol) и могут иметь опциональные аргументы в скобках. Фильтры можно объединять (связывать). Результат выполнение одного фильтра передаётся на вход следующему.

В данном примере происходит удаление HTML-тегов из переменной name и последующая смена всех символов на их заглавные версии:

Фильтры, которые принимают дополнительные аргументы, содержат перечень этих аргументов между ( и ) скобками. В приведённом примере список значений будет объединён символом запятой:

Чтобы применить фильтр к секции кода воспользуйтесь тегом filter :

Со списком всех доступных фильтров можно ознакомиться по этой ссылке.

Функции

Функции могут быть вызваны для генерирования содержимого шаблонов и состоят из имени, скобок и опционального списка аргументов.

Для примера, функция range возвращает массив чисел от начального значения до конечного с определенным шагом:

Со списком всех доступных функций можно ознакомиться по этой ссылке.

Именованые аргументы

Использование именованных аргументов делает вызов в шаблоне понятным и даёт дополнительную информацию о предназначении передаваемых параметров:

Именованные аргументы так же позволяют пропустить некоторые из передаваемых аргументов, для которых вы не хотите менять значения по-умолчанию:

Безусловно есть возможность использования как именованных аргументов так и неименованных в одном вызове, однако необходимо помнить, что неименованные аргументы всегда должны следовать первыми:

На страницах документации, в описании каждого метода и фильтра, присутствует полный перечень поддерживаемых параметров и их наименований.

Управляющие структуры

К управляющим структурам относятся всё то, что влияет на логику (течение) работы программы - условия ( if , elseif , else ), for -циклы и блоки. Управляющие структуры используются между тегами .

Например, чтобы отобразить список пользователей, которые хранятся в переменной users воспользуемся for -тегом:

Тег if может быть использован для проверки выражений:

Для ознакомления со всем перечнем поддерживаемых тегов перейдите по этой ссылке.

Комментарии

Чтобы закомментировать часть кода или строки в шаблоне воспользуйтесь тегом . Крайне полезная возможности при отладке или необходимости внесения дополнительных пояснений в логику отображения.

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

Функция подключения шаблонов полезна тем, что с её помощью можно в существующий шаблон вставить содержимое другого шаблона для выполнение в текущем контексте:

По-умолчанию включаемые шаблоны имеют доступ к тому же контексту в шаблоне которого они вызываются. Это означает, что любая переменная, объявленная в основном шаблоне, будет доступна и в подключаемом тоже:

Подключаемый шаблон render_box.html имеет доступ к переменной box .

Наименование подключаемого шаблона зависит от использованного системного загрузчика. Для примера, Twig_Loader_Filesystem позволяет получить доступ к шаблону с указанием полного пути к файлу шаблона, а это значит, что есть возможность получить доступ к шаблону используя / для перехода в нужную директорию:

Такая возможность, по использованию доступа к шаблону по пути в файловой системе относительно проекта, доступна в зависимости от настроек приложения использующего шаблонизатор Twig.

Наследование шаблонов

Сильной стороной Twig является наличие наследования шаблонов. Наследование шаблонов позволяет создать своего рода "скелет" отображения, которое содержит все необходимые элементы сайта и определяет block -теги (блоки), которые дочерние шаблоны могут перезаписывать и переопределять.

Звучит ужасающе, но всё намного проще! Лучше способ понять - начать с небольшого примера.

Давайте определим базовый шаблон, base.html , который описывает общую HTML-структуру страницы с двумя колонками, которую вы могли бы использовать у себя на сайте:

В этом примере объявляются 4 блока, которые могут быть перезаписаны в дочерних шаблонах. Всё, что делают block -теги, так это сообщают шаблонизатору о том, что у дочерних шаблонов есть возможность перезаписать содержимое этих блоков.

Дочерний шаблон, в свою очередь, может выглядеть следующим образом:

Ключевым здесь является extends -тег. Этот тег сообщает шаблонизатору, что текущий шаблон "расширяет" / наследуется от другого шаблона. На момент анализа шаблона система, в первую очередь, определяет родительский шаблон. extends -тег должен быть первым тегом в шаблоне.

Обратите внимание, что дочерний шаблон не определяет блок footer , это значит, что будет использовано содержимое родительского шаблона.

Есть возможность отобразить содержимое родительского блока при помощи вызова функции parent() . Вызов этой функции возвращает содержимое родительского блока:

Twig так же поддерживает множественное наследование по так называемой методике "горизонтального переиспользование" (horizontal reuse) с помощью use -тега. В большинстве случаев вам даже не понадобится погружаться так глубоко и использовать этот подход при проектировании шаблонов.

Экранирование HTML

Генерируя HTML-код всегда есть некоторая вероятного того, что в переменной будет содержаться HTML-разметка, которая повлияет на результат отображения. Существует два подхода к решению такой задачи: ручное экранирование каждой выводимой переменной и автоматическое экранирование всех выводимых переменных по-умолчанию.

Twig поддерживает оба варианта, а второй является вариантом используемым по-умолчанию.

Автоматическое экранирование может быть настроено с помощью тега autoescape и по-умолчанию работает с опцией html .

Ручное экранирование

Если режим ручного экранирования переменных активен, то экранирование выводимых переменных ложится полностью на ваши плечи. Что экранировать? Любую перменную, содержимому которой вы не доверяете.

Экранирование работает через использование соответствующих фильтров - escape и e .

По-умолчанию escape -фильтр использует стратегию экранирования html , однако, в зависимости от используемого контекста, есть возможность указать другие стратегии:

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

Независимо от того, включено или нет автоматическое экранирование, есть возможность указать конкретный блок кода, который должен экранироваться используя autoescape -тег.

По-умолчанию autoescape -тег использует html -стратегию экранирования.

Если необходимо отобразить переменную в другом контексте, то воспользуйтесь одной из имеющихся стратегий экранирования, как показано в примере:

Экранирование

Иногда может возникнуть необходимость проигнорировать выводимую часть шаблона, которую, при обычной логике обработки, шаблонизатор бы воспринял, как часть кода. Например, если используется синтаксис по-умолчанию и вы хотите вывести строку

Для больший секций кода, который необходимо проигнорироваться, есть смысл воспользвоаться verbatim -тегом.

Макросы

Макросы сравнимы с функциями в обычных языках программирования. Они полезны в случаях, когда необходимо переиспользовать часто используемые блоки HTML-кода.

Макрос определяется macro -тегом. Приведём небольшой пример макроса, который отображает элемент формы:

Макрос может быть определён в любом шаблон и импортирован с использованием import -тега перед использованием:

Кроме того, вы можете имортировать единичный макрос из шаблона в текущий контекст воспользовавшись from -тегом и, по необходимости, указанием псевдонима вызываемого макроса.

Значения по-умолчанию так же могут быть установлены при описании максроса:

Если при вызове макроса передаются дополнительные параметры (вне описанных), то их значения будут доступны в переменной varargs .

Выражения

Выражения в Twig могут быть повсюду. Они ведут себя таким же образом, как в PHP. Если вы не используете PHP, то всё равно будете чувствовать себя комфортно используя их.

Список операторов в порядке увеличения приоритета выполнения:

Константы

Самый простые выражения - константы. Константы представляют собой PHP-значения различны типов.

Какие существуют константы:

"Hello World" : Всё, что располагается между ординарными или двойными кавычками является строкой.
42 / 42.5 : целочисленное значение и значение с плавающей запятой.
["foo", "bar"] : массивы объявляются перечислением элементов обрамлённых квадратными скобками.
: хэш-массивы объявляются перечислением пар ключ-значение обрамлённых фигурными скобками.

true/false : true - истинное значение, false - ложное.
null : null обозначает отсутствуе какого-либо значения. Это значение возвращается в том случае, если переменная не существует. none это псевдоним null .

Массивы и хэш-массивы могут быть вложенными:

Использование одинарных кавычек или двойных никак не сказывается на производительности или скорости обработки, однако стоит иметь ввиду, что интерполяция переменных возможна только в строке обрамлённой двойными кавычками.

Математические операторы

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

Следующие операторы доступны:

+ : сложение
- : вычитание
/ : деление, возвращает значение с плавающей точкой
% : деление по модулю, возвращает целочисленный остаток от деления двух целочисленных значений
// : деление двух целочисленных значение, возвращает целое значение округлённой вниз
* : умножение
** : возведение в степень, возводит значение левого операнда в степень правого ( > = 8)

Логические операторы

Комбинирование нескольких выражений возможно при помощи следующих логических операторов:

and : и
or : или
not : не
(выражение) : группировка выражений для изменения приоритета

Операторы являются регистро-зависимыми.

Сравнения

Следующие операторы сравнения доступны в любых выражениях: == , != , < , > , >= , <= .

Так же возможна проверка, если строка starts with (начинается с) или ends with (заканчивается на) определенное значение.

Для более сложных сравнений используется оператор matches , который поддерживает регулярные выражения:

Оператор содержания

Оператор in осуществляет проверку на содержание.

Возвращает true , если левый операнд содержится в правом:

Использование данного оператора возможно с массивами, строками, объектами реализующими интерфейс Traversable .

Для осуществления отрицательной проверки на содержание воспользуйтесь not in :

Оператор тестирования

Оператор is осуществляет тестирование. Тестирование предназначено для проверки переменных соблюдению/выполнению определенных условий. Правый операнд - название теста:

Тесты могут принимать аргументы:

Тесты могут быть негативными / отрицательными с использованияем is not :

Другие операторы

Следующие операторы не попадают ни в одну из перечисленных ранее категорий:

| : применяет фильтр
.. : создаёт последовательности в которой левый операнд выступает начальным значением, а правый - конечным. Является синтаксическим сахаром для вызова функции range ):

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

Интерполяция строк

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

Контроль пробелов

Используйте тег ```spaceless`` для удаление всех пробелов в HTML-коде между HTML-тегами:

В дополнение к имеющемуся spaceless -тегу есть возможность контролировать наличие пробелов на уровне единичных тегов. Используя специальный модификатор пробелов есть возможность контролировать отображение пробелов, как в начале, так и в конце выражения.

Приведенный выше пример демонстрирует стандартное поведение модификатора пробелов и возможность удаления пробелов вокруг тегов. Использование модификатора пробелов на одной из сторон приведёт к удалению всех пробелов на этой стороне до следующего HTML-тега.

Расширения

Twig может быть очень просто расширен произвольными тегами, функциями и фильтрами. Если вы хотите воспользоваться уже разработанными community-расширениями, то обязательно загляните в официальный репозиторий расширений.

Если же вы хотите разработать собственные расширения, то изучите главу "Создание расширений".

Читайте также: