Данная библиотека позволяет использовать twig шаблоны в компонентах 1С Битрикс. Обрабатываются файлы, имеющие расширение .twig. Если создать в директории шаблона компонента файл template.twig, то именно он будет использоваться при генерации шаблона. К сожалению, ядро битрикса так устроено, что при наличии двух файлов .php и .twig, будет использовать только .php, поэтому для использования twig шаблона нужно позаботиться о том, чтобы php шаблон отсутствовал.

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

vendor:component_name[:template[:specific_template_file]]

Здесь

• vendor - это пространство имен разработчика, например bitrix или maximaster
• component_name - имя компонента, шаблон которого наследуется
• template - имя шаблона, который нужно унаследовать. Необязательный, по-умолчанию .default
• specific_template_file - конкретный файл шаблона (без расширения). Необязательный, по-умолчанию template

Например, вы хотите унаследовать шаблон new-year компонента maximaster:product. Для этого в шаблоне twig нужно написать

{% extends "maximaster:product:new-year" %}

Библиотека конфигурируется с помощью файла /bitrix/.settings.php. Нужно завести в этом файле опцию maximaster, и оперировать значением tools->twig. Ниже описаны значения опций, которые заданы библиотекой по-умолчанию:

//...
'maximaster' => array(
    'value' => array(
        'tools' => array(
            'twig' => array(
				// Режим отладки выключен
				'debug' => false,

				//Кодировка соответствует кодировке продукта
				'charset' => SITE_CHARSET,

				//кеш хранится в уникальной директории
				'cache' => $_SERVER['DOCUMENT_ROOT'] . '/bitrix/cache/maximaster/tools.twig',

				//Автообновление включается только в момент очистки кеша
				'auto_reload' => isset( $_GET[ 'clear_cache' ] ) && strtoupper($_GET[ 'clear_cache' ]) == 'Y',

				//Автоэскейп отключен, т.к. битрикс по-умолчанию его сам делает
				'autoescape' => false,
            )
        )
    )
)
//...

При выборе значений для конфигов нужно опираться на документацию twig по настройкам Twig_Environment. Поддерживаются все возможные согласно этой документации опции

С версии 0.5 появилась возможность добавления собственных расширений. Реализуется это с помощью обработчика события onAfterTwigTemplateEngineInited. Событие не привязано ни к одному из модулей, поэтому при регистрации события в качестве идентификатора модуля нужно указать пустую строку. В событие передается объект \Twig_Environment, с которым можно сделать определенные манипуляции. Пример обработчика события, который зарегистрирует свое расширение:

use Bitrix\Main\EventResult;

class onAfterTwigTemplateEngineCreated
{
    public static function addTwigExtension(\Twig_Environment $engine)
    {
        $engine->addExtension(new MySuperDuperExtension());
        return new EventResult(EventResult::SUCCESS, array($engine));
    }
}

Здесь класс MySuperDuperExtension должен быть наследником класса \Twig_Extension или имплементацией интерфейса \Twig_ExtensionInterface.

С версии 0.5 в библиотеке появились дополнительные удобные функции для работы с шаблонами. На данный момент функция только одна, но их перечень постоянно будет пополняться.

Функция помогает в выводе множественного числа для русских слов. К примеру, вам нужно вывести строку "21 билет". Для этого нужно воспользоваться функцией с такими параметрами в twig:

    {% set ticketsCount = 21 %}
    {{ russianPluralForm(ticketsCount, ['билетов', 'билет', 'билета']) }}

Порядок словоформ запомнить достаточно просто: 0 билетов, 1 билет, 2 билета. Для большинства слов такой порядок будет работать корректно.