Дата обновления перевода 2021-06-08

Справочник конфигурации Twig (TwigBundle)

TwigBundle интегрирует библиотеку Twig в приложения Symfony, чтобы отображать шаблоны. Все эти опции конфигурируются под ключом twig в конфигурации вашего приложения.

1
2
3
4
5
# отображает значения кофнигурации по умолчанию определенные Symfony
$ php bin/console config:dump-reference twig

# отображает реальные значения конфигурации, используемые вашим приложением
$ php bin/console debug:config twig

Note

При использованиии XML, вы должны использовать пространство имен http://symfony.com/schema/dic/twig, а связанная XSD-схема доступна тут: https://symfony.com/schema/dic/twig/twig-1.0.xsd

Конфигурация

auto_reload

тип: boolean по умолчанию: '%kernel.debug%'

Если true, то каждый раз при отображении шаблона Symfony вначале проверяет, изменился ли исходный код после последней компиляции. Если изменился, то шаблон компилируется снова автоматически.

autoescape

тип: boolean or string по умолчанию: 'name'

Если false, то автоматическое экранирование отключено (вы всё равно можете экранировать содержимое индивидуально в шаблонах).

Caution

Установка этой опции, как false опасна, и сделает ваше приложение уязвимым к эксплуатации XSS, так как большинство сторонних пакетов предполагают, что экранирование подключено и самостоятельно не экранируют содержимое.

Если оно установлено, как строка, то содержимое шаблона экранируется с использованием стратегии с этим имеем. Разрешённые значения: html, js, css, url, html_attr и name. Значение по умолчанию - name. Эта стратегия экранирует содержимое в соответствии с расширением имени шаблона (например, использует html для шаблонов *.html.twig, и js для шаблонов *.js.html).

Tip

См. autoescape_service и autoescape_service_method чтобы определить вашу собственную стратегию экранирования.

autoescape_service

тип: string по умолчанию: null

Начиная с Twig 1.17, стратегия экранирования, применённая по умолчанию к шаблону, определяется во время компиляции, основываясь на имени файла щаблона. Это означает, к примеру, что содержимое шаблона *.html.twig экранируется для HTML, а содержимое *.js.twig - для JavaScript.

Эта опция позволяет определить сервис Symfony, который будет использован, чтобы определить экранирование по умолчанию, применённое к шаблону.

autoescape_service_method

тип: string по умолчанию: null

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

base_template_class

тип: string по умолчанию: 'Twig_Template'

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

cache

тип: string по умолчанию: '%kernel.cache_dir%/twig'

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

Установите эту опцию как false, чтоб отключить компиляцию шаблона Twig. Однако, это не рекомендуется; даже в окружении dev, так как опация auto_reload гарантирует, что изменённые кешированные шаблоны будут скомпилированы опять.

charset

тип: string по умолчанию: '%kernel.charset%'

Набор символов, используемый файлами шаблонов. По умолчанию, это то же значение, что и параметр контейнера kernel.charset, который по умолчанию в приложениях Symfony установлен, как UTF-8.

date

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

format

тип: string по умолчанию: F j, Y H:i

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

internal_format

тип: string по умолчанию: %d days

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

timezone

тип: string по умолчанию: (значение, возвращённое date_default_timezone_get())

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

debug

тип: boolean по умолчанию: '%kernel.debug%'

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

default_path

тип: string по умолчанию: '%kernel.project_dir%/templates'

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

form_themes

тип: array в string по умолчанию: ['form_div_layout.html.twig']

Определяет одну или более тему формы, который применяются ко всем формам приложения:

  • YAML
    1
    2
    3
    4
    # config/packages/twig.yaml
    twig:
        form_themes: ['bootstrap_4_layout.html.twig', 'form/my_theme.html.twig']
        # ...
    
  • XML
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    <!-- config/packages/twig.xml -->
    <?xml version="1.0" encoding="UTF-8" ?>
    <container xmlns="http://symfony.com/schema/dic/services"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:twig="http://symfony.com/schema/dic/twig"
        xsi:schemaLocation="http://symfony.com/schema/dic/services
            https://symfony.com/schema/dic/services/services-1.0.xsd
            http://symfony.com/schema/dic/twig https://symfony.com/schema/dic/twig/twig-1.0.xsd">
    
        <twig:config>
            <twig:form-theme>bootstrap_4_layout.html.twig</twig:form-theme>
            <twig:form-theme>form/my_theme.html.twig</twig:form-theme>
            <!-- ... -->
        </twig:config>
    </container>
    
  • PHP
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    // config/packages/twig.php
    use Symfony\Config\TwigConfig;
    
    return static function (TwigConfig $twig) {
        $twig->formThemes([
            'bootstrap_4_layout.html.twig',
            'form/my_theme.html.twig',
        ]);
    
        // ...
    };
    

Порядок, в котором определяется темы, важен, так как каждая тема переопределяет все предыдущие. При отображении поля формы, блок которой не определен в теме формы, Symfony использует предыдущие темы до первой.

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

globals

тип: array по умолчанию: []

Определяет клобальные переменные автоматически внедренные во все шаблоны Twig. Узнайте больше о глобальных переменных Twig.

number_format

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

decimals

тип: integer по умолчанию: 0

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

decimal_point

тип: string по умолчанию: .

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

thousands_separator

тип: string по умолчанию: ,

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

optimizations

тип: int по умолчанию: -1

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

По умолчаниб, эта опция - -1, что означает, что все оптимизации включены. Установите её как 0, чтобы отключить все оптимизации. Вы даже можете включить или отключить эти оптимизации выборочно, как объясняется в документации Twig о расширении оптимизатора.

paths

тип: array по умолчанию: null

Определяет каталоги, где Symfony будет искать шаблоны Twig в дополнение к каталогу, определенному в опции default_path:

  • YAML
    1
    2
    3
    4
    5
    6
    # config/packages/twig.yaml
    twig:
        # ...
        paths:
            'email/default/templates': ~
            'backend/templates': 'admin'
    
  • XML
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    <!-- config/packages/twig.xml -->
    <container xmlns="http://symfony.com/schema/dic/services"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:twig="http://symfony.com/schema/dic/twig"
        xsi:schemaLocation="http://symfony.com/schema/dic/services
            https://symfony.com/schema/dic/services/services-1.0.xsd
            http://symfony.com/schema/dic/twig https://symfony.com/schema/dic/twig/twig-1.0.xsd">
    
        <twig:config>
            <!-- ... -->
            <twig:path>email/default/templates</twig:path>
            <twig:path namespace="admin">backend/templates</twig:path>
        </twig:config>
    </container>
    
  • PHP
    1
    2
    3
    4
    5
    6
    7
    8
    9
    // config/packages/twig.php
    use Symfony\Config\TwigConfig;
    
    return static function (TwigConfig $twig) {
        // ...
    
        $twig->path('email/default/templates', null);
        $twig->path('backend/templates', 'admin');
    };
    

Прочтите больше о каталогах и пространствах имен шаблонов.

strict_variables

тип: boolean по умолчанию: false

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

Эта документация является переводом официальной документации Symfony и предоставляется по свободной лицензии CC BY-SA 3.0.