Twig

В этой главе описывается API для Twig, a не язык шаблонов. Это будет наиболее полезным в качестве ссылки для тех, кто реализует интерфейс шаблонов для приложений , а не тем, кто создает шаблоны Twig.

Основы

Twig использует центральный объект, называемый environment (класс Twig_Environment). Экземпляры этого класса используются для хранения конфигурации и расширений и используются для загрузки шаблонов из файловой системы или других мест.

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

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

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

$loader = new Twig_Loader_Filesystem('/path/to/templates');
$twig = new Twig_Environment($loader, array(
    'cache' => '/path/to/compilation_cache',
));

Это создаст среду шаблона с настройками по умолчанию и загрузчик, который ищет шаблоны в папке /path/to/templates/. Также доступны различные загрузчики и вы можете написать свой ​​собственный, если вы хотите загрузить шаблоны из базы данных или других ресурсов.

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

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

Для загрузки шаблона из этой среды вам просто нужно вызвать loadTemplate() метод, который возвращает затем экземпляр Twig_Template:

$template = $twig->loadTemplate('index.html');

Чтобы передать переменные в шаблон, вызовите метод render():

echo $template->render(array('the' => 'variables', 'go' => 'here'));

Метод display() это наиболее простой метод вывести шаблон явно.

Вы можете также загрузить и воспроизвести шаблон одновременно:

echo $twig->render('index.html', array('the' => 'variables', 'go' => 'here'));

Опции окружения.

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

$twig = new Twig_Environment($loader, array('debug' => true));

Доступны следующие опции:

• debug: При установке в true, генерируемые шаблоны имеют__toString() метод, который можно использовать для отображения сгенерированных узлов (по умолчанию false).
• charset: Кодировка, используемая в шаблонах (по умолчанию в UTF-8)
• base_template_class: Шаблон базового класса ,который используют для сгенерированных шаблонов (по умолчанию Twig_Template).
• cache: Абсолютный путь, где хранятся скомпилированные шаблоны или false чтобы отключить кэширование (который по умолчанию).
• auto_reload: При разработке с Twig, полезно повторно компилировать шаблон при изменении кода-исходника. Если вы не установили значение опции auto_reload, то она будет определена автоматически на основании переменной debug.
• strict_variables: Если установлено false, Twig будет по умолчанию игнорировать недействительные переменные (переменные и или атрибуты/методы, которые не существуют) и заменять их значением null. Когда устанавлено true, Twig генерирует исключение (по умолчанию false).
• autoescape: Если установить true, авто-сохранение будет разрешено по умолчанию для всех шаблонов (по умолчанию true). Начиная с Twig 1.8, вы можете выбрать какую методику сохранения использовать (html, js, false для блокировки). Начиная с Twig 1.9, вы можете выбрать какую методику сохранения использовать (css, url, html_attr, или обратный вызов PHP, который берет шаблон "имя файла" и должен вернуть методику сохранения для использования -- обратный вызов не может быть названием функции, чтобы избежать конфликта (коллизии) со встроенными методами сохранения. optimizations: Флаг, который указывает, какие оптимизации применять (по умолчанию -1 -- все оптимизации разрешены; установите его на 0 для отключения).

Загрузчики

Загрузчики отвечают за загрузку шаблонов из такого ресурса, как файловая система.

Компиляция кэша

Все загрузчики шаблонов могут кэшировать компилированные шаблоны в файловой системе для дальнейшего использования. Это значительно ускоряет Twig, поскольку шаблоны компилируются только один раз и увеличение производительности даже больше, если бы вы использовали ускоритель PHP, такой как APC. Смотрите cache и auto_reload опции Twig_Environment выше для получения подробной информации.

Встроенные загрузчики

Вот список встроенных загрузчиков, которые дает Twig:

Twig_Loader_Filesystem

Новое в версии 1.10: prependPath() и поддержка пространства имен были добавлены в Twig 1.10.

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

$loader = new Twig_Loader_Filesystem($templateDir);

Он может также искать шаблоны в массиве директорий:

$loader = new Twig_Loader_Filesystem(array($templateDir1, $templateDir2));

При такой конфигурации Twig будет сначала искать шаблоны в $templateDir1 и если они не существуют, и он будет искать их в $templateDir2.

Вы можете добавить или вставить каналы (пути) с помощью методов addPath() и prependPath().

$loader->addPath($templateDir3);
$loader->prependPath($templateDir4);

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

Используя методы setPaths(), addPath(), и prependPath(), определите пространство имен как второй аргумент ( если нет определения, то эти методы действуют на пространстве имени "main").

$loader->addPath($templateDir, 'admin');

Шаблоны пространства имен могут быть доступны через специальное обозначение @namespace_name/template_path:

$twig->render('@admin/index.html', array());

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

$loader = new Twig_Loader_String();
$twig = new Twig_Environment($loader);

echo $twig->render('Hello {{ name }}!', array('name' => 'Fabien'));

Этот загрузчик следует использовать только для unit-тестирования , поскольку он имеет строгие ограничения: несколько тегов, такие как extends или include не имеет смысла использовать, поскольку ссылка на шаблон сама является кодом источника шаблона.

Twig_Loader_Array загружает шаблон из PHP массива. Это передается ограничением массива строк до имен шаблонов.

$loader = new Twig_Loader_Array(array(
    'index.html' => 'Hello {{ name }}!',
));
$twig = new Twig_Environment($loader);

echo $twig->render('index.html', array('name' => 'Fabien'));

Этот загрузчик очень полезен для unit-тестирования. Он также может быть использован для малых проектов, где хранение всех шаблонов может иметь смысл в одном PHP файле.

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

Twig_Loader_Chain перенаправляет загрузку шаблонов к другим загрузчикам:

$loader1 = new Twig_Loader_Array(array(
    'base.html' => '{% block content %}{% endblock %}',
));
$loader2 = new Twig_Loader_Array(array(
    'index.html' => '{% extends "base.twig" %}{% block content %}Hello {{ name }}{% endblock %}',
    'base.html'  => 'Will never be loaded',
));

$loader = new Twig_Loader_Chain(array($loader1, $loader2));

$twig = new Twig_Environment($loader);

При поиске шаблона Twig будет пробовать каждый загрузчик по очереди и он будет возвращаться как только шаблон найдется. При рендеринге шаблона index.html из вышеуказанного примера, Twig будет пытаться загрузить его с помощью $loader2, но base.html будет загружен из $loader1.

Twig_Loader_Chain принимает любой загрузчик, который реализует Twig_LoaderInterface.

Вы также можете добавить загрузчики с помощью addLoader() метода.

Создайте свой собственный загрузчик

Все загрузчики реализуют Twig_LoaderInterface:

interface Twig_LoaderInterface
{
    /**
     * Gets the source code of a template, given its name.
     *
     * @param  string $name string The name of the template to load
     *
     * @return string The template source code
     */
    function getSource($name);

    /**
     * Gets the cache key to use for the cache for a given template name.
     *
     * @param  string $name string The name of the template to load
     *
     * @return string The cache key
     */
    function getCacheKey($name);

    /**
     * Returns true if the template is still fresh.
     *
     * @param string    $name The template name
     * @param timestamp $time The last modification time of the cached template
     */
    function isFresh($name, $time);
}

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

class Twig_Loader_String implements Twig_LoaderInterface
{
    public function getSource($name)
    {
      return $name;
    }

    public function getCacheKey($name)
    {
      return $name;
    }

    public function isFresh($name, $time)
    {
      return false;
    }
}

Метод isFresh() должен вернуть true, если текущий шаблон в кэше еще свежий, учитывая время последнего изменения или false в противном случае.

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

Использование расширений

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

$twig->addExtension(new Twig_Extension_Sandbox());

Twig поставляется в комплекте со следующими расширениями:

• Twig_Extension_Core: Определяет все основные возможности Twig.
• Twig_Extension_Escaper: Добавляет автоматический вывод данных-сохранение, а также возможность сохранить/пропустить блоки кода.
• Twig_Extension_Sandbox: Добавляет изолированный режим в среду Twig по умолчанию, что делает его безопасным для оценки ненадежного кода.
• Twig_Extension_Optimizer: Оптимизирует древо узлов перед компиляцией.

Расширения сore, escaper и optimizer не нужно добавлять к среде Twig environment, так как они выставлены по умолчанию.

Встроенные расширения

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

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

Расширениe ядра

Расширения ядра определяет все основные особенности Twig:

• Теги;
• Фильтры;
• Функции;
• Тесты

Расширение Escaper

Расширение escaper добавляет автоматическое сохранение вывода в Twig. Это определяет тег autoescape и фильтр raw.

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

$escaper = new Twig_Extension_Escaper('html');
$twig->addExtension($escaper);

Если установлено HTML, все переменные в шаблонах будут сохранены (с помощью HTML стратегии сохранения), за исключением тех, которые используют фильтр raw:

{{ article.to_html|raw }}

Вы также можете изменить режим сохранения локально с помощью тега autoescape (смотрите autoescape документ для синтаксиса, используемого до Twig 1.8):

{% autoescape 'html' %}
    {{ var }}
    {{ var|raw }}      {# var won't be escaped #}
    {{ var|escape }}   {# var won't be double-escaped #}
{% endautoescape %}

Правила сохранения реализуются следующим образом:

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

{{ "Twig<br />" }} {# won't be escaped #}

{% set text = "Twig<br />" %}
{{ text }} {# will be escaped #}

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

{{ foo ? "Twig<br />" : "<br />Twig" }} {# won't be escaped #}

{% set text = "Twig<br />" %}
{{ foo ? text : "<br />Twig" }} {# will be escaped #}

{% set text = "Twig<br />" %}
{{ foo ? text|raw : "<br />Twig" }} {# won't be escaped #}

{% set text = "Twig<br />" %}
{{ foo ? text|escape : "<br />Twig" }} {# the result of the expression won't be escaped #}

• Сохранение применяется перед печатью, после любого другого фильтра:

{{ var|upper }} {# is equivalent to {{ var|upper|escape }} #}

• Грубый фильтр следует использовать только в конце цепочки фильтров:

{{ var|raw|upper }} {# will be escaped #}
{{ var|upper|raw }} {# won't be escaped #}

• Автоматическое сохранение не применяется, если последний фильтр в цепочке помечен как безопасный для текущего контекста (например, html или js). escape и escape('html') отмечен безопасным для HTML, escape('js') отмечен безопасным для JavaScript, raw отмечен безопасным для всего остального.

{% autoescape 'js' %}
    {{ var|escape('html') }} {# will be escaped for HTML and JavaScript #}
    {{ var }} {# will be escaped for JavaScript #}
    {{ var|escape('js') }} {# won't be double-escaped #}
{% endautoescape %}

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

Расширение Sandbox

Расширения «песочницы» могут быть использованы для оценки небезопасного кода. Доступ к небезопасным свойствам и методам запрещен.

Безопасность «песочницы» регулируется policy instance. По умолчанию Twig обладает лишь одной классовой политикой: Twig_Sandbox_SecurityPolicy. Этот класс позволяет внести в «белый» список некоторые тэги, фильтры, значения и методы:

$tags = array('if');
$filters = array('upper');
$methods = array(
    'Article' => array('getTitle', 'getBody'),
);
$properties = array(
    'Article' => array('title', 'body'),
);
$functions = array('range');
$policy = new Twig_Sandbox_SecurityPolicy($tags, $filters, $methods, $properties, $functions);

С такими настройками вы можете использование лишь тег if и фильтр upper. Кроме того, шаблоны будут способны вызывать только методы getTitle() и getBody() в объекте Article а title и body становятся общедоступными свойствами. Все остальные методы и свойства будут запрещены, и при обращении к ним будет генерировать Twig_Sandbox_SecurityError исключение.

Объект policy является первым аргументом конструктора Sandbox:

$sandbox = new Twig_Extension_Sandbox($policy);
$twig->addExtension($sandbox);

По умолчанию режим Sandbox отключен и его следует включить, когда включается ненадежный код шаблона тега sandbox:

{% sandbox %}
    {% include 'user.html' %}
{% endsandbox %}

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

$sandbox = new Twig_Extension_Sandbox($policy, true);

Расширение оптимизации

Расширение optimizer оптимизирует древо узлов до компиляции:

$twig->addExtension(new Twig_Extension_Optimizer());

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

$optimizer = new Twig_Extension_Optimizer(Twig_NodeVisitor_Optimizer::OPTIMIZE_FOR);
$twig->addExtension($optimizer);

Twig поддерживает следующие оптимизации:

• Twig_NodeVisitor_Optimizer::OPTIMIZE_ALL, включает все оптимизации(это значение по умолчанию).
• Twig_NodeVisitor_Optimizer::OPTIMIZE_NONE, Отключает все оптимизации. Это сокращает время компиляции, но может увеличить время исполнения и потребляемую память.
• Twig_NodeVisitor_Optimizer::OPTIMIZE_FOR, оптимизация for тега с помощью удаления создания переменной цикла, когда это возможно.
• Twig_NodeVisitor_Optimizer::OPTIMIZE_RAW_FILTER, удаляет необработанный фильтр всякий раз, когда это возможно.
• Twig_NodeVisitor_Optimizer::OPTIMIZE_VAR_ACCESS, упрощает создание и доступ переменных в скомпилированные шаблоны, когда это возможно.

Исключения

Twig может выбрасывать исключения:

• Twig_Error: Основное исключение для всех ошибок.
• Twig_Error_Syntax: Выбрасывается для того, чтобы сообщить пользователю, что есть проблема с синтаксисом шаблона.
• Twig_Error_Runtime: Выбрасывается когда возникает ошибка во время выполнения (например, когда фильтр не существует).
• Twig_Error_Loader: Выбрасывается при возникновении ошибки во время загрузки шаблона.
• Twig_Sandbox_SecurityError: Выбрасывается когда неразрешенный тег, фильтр, или метод вызывается из изолированного шаблона.