Конфигурация TwigBundle ("twig")

Конфигурация TwigBundle ("twig")

  • YAML
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    # app/config/config.yml
    twig:
        exception_controller:  twig.controller.exception:showAction
    
        form_themes:
    
            # По умолчанию:
            - form_div_layout.html.twig
    
            # Bootstrap:
            - bootstrap_3_layout.html.twig
            - bootstrap_3_horizontal_layout.html.twig
    
            # Основание
            - foundation_5_layout.html.twig
    
            # Пример:
            - MyBundle::form.html.twig
    
        globals:
    
            # Примеры:
            foo:                 '@bar'
            pi:                  3.14
    
            # Опции примеров, но наиболее простой в использовании показан выше
            some_variable_name:
                # id сервиса, который должен быть значением
                id:                   ~
                # устновить сервис или оставить пустым
                type:                 ~
                value:                ~
        autoescape:                ~
    
        # См. http://twig.sensiolabs.org/doc/recipes.html#using-the-template-name-to-set-the-default-escaping-strategy
        autoescape_service:        ~ # Example: 'my_service'
        autoescape_service_method: ~ # use in combination with autoescape_service option
        base_template_class:       ~ # Example: Twig_Template
        cache:                     '%kernel.cache_dir%/twig'
        charset:                   '%kernel.charset%'
        debug:                     '%kernel.debug%'
        strict_variables:          ~
        auto_reload:               ~
        optimizations:             ~
        paths:
            '%kernel.project_dir%/vendor/acme/foo-bar/templates': foo_bar
    
  • XML
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    <!-- app/config/config.xml -->
    <?xml version="1.0" charset="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
            http://symfony.com/schema/dic/services/services-1.0.xsd
            http://symfony.com/schema/dic/twig http://symfony.com/schema/dic/twig/twig-1.0.xsd">
    
        <twig:config
            auto-reload="%kernel.debug%"
            autoescape="name"
            base-template-class="Twig_Template"
            cache="%kernel.cache_dir%/twig"
            charset="%kernel.charset%"
            debug="%kernel.debug%"
            strict-variables="false"
            optimizations="true"
        >
            <twig:form-theme>form_div_layout.html.twig</twig:form-theme> <!-- Default -->
            <twig:form-theme>MyBundle::form.html.twig</twig:form-theme>
    
            <twig:global key="foo" id="bar" type="service" />
            <twig:global key="pi">3.14</twig:global>
    
            <twig:exception-controller>AcmeFooBundle:Exception:showException</twig:exception-controller>
            <twig:path namespace="foo_bar">%kernel.project_dir%/vendor/acme/foo-bar/templates</twig:path>
        </twig:config>
    </container>
    
  • PHP
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    // app/config/config.php
    $container->loadFromExtension('twig', array(
        'form_themes' => array(
            'form_div_layout.html.twig', // Default
            'MyBundle::form.html.twig',
         ),
         'globals' => array(
             'foo' => '@bar',
             'pi'  => 3.14,
         ),
         'auto_reload'          => '%kernel.debug%',
         'autoescape'           => 'name',
         'base_template_class'  => 'Twig_Template',
         'cache'                => '%kernel.cache_dir%/twig',
         'charset'              => '%kernel.charset%',
         'debug'                => '%kernel.debug%',
         'strict_variables'     => false,
         'exception_controller' => 'AcmeFooBundle:Exception:showException',
         'optimizations'        => true,
         'paths' => array(
             '%kernel.project_dir%/vendor/acme/foo-bar/templates' => 'foo_bar',
         ),
    ));
    

Caution

Ключ конфигурации twig.form (тег <twig:form /> для xml) устарел и будет удалён в версии 3.0. Вместо этого, используйте опцию twig.form_themes.

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

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-код. Компиляция - это затратный процесс, так что результат кешируется в каталог, определённый этой опцией конфигурации.

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

charset

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

Набор символов, использованный файлами шаблонов. В Стандартной версии Symfony набор символов по умолчанию - UTF-8.

debug

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

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

exception_controller

тип: string по умолчанию: twig.controller.exception:showAction

Это контроллер, который активируется после того, как вызывается исключение где-либо в вашем приложении. Контроллер по умолчанию (ExceptionController) отвечает за отображение конкретных шаблонов при разных условиях ошибок (см. How to Customize Error Pages). Изменения этой опции - продвинутый уровень. Если вам нужно настроить страницу ошибки, вам стоит использовать предыдущую ссылку. Если вам нужно выполнить некоторое поведение в исключении, вам стоит добавить слушателя к событию kernel.exception (см. kernel.event_listener).

optimizations

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

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

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

paths

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

Эта опция определяет каталоги, в которых Symfony будет искать шаблоны Twig в дополнение к локациям по умолчанию (app/Resources/views/ и каталоги пакетов Resources/views/). Это полезно для интеграции шаблонов, включённых в какую-то библиотеку или пакет, использованные вашим приложением.

Значения опции paths определяются как пары key: value, где часть value может быть null. Например:

  • YAML
    1
    2
    3
    4
    5
    # app/config/config.yml
    twig:
        # ...
        paths:
            '%kernel.project_dir%/vendor/acme/foo-bar/templates': ~
    
  • XML
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    <!-- app/config/config.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
            http://symfony.com/schema/dic/services/services-1.0.xsd
            http://symfony.com/schema/dic/twig http://symfony.com/schema/dic/twig/twig-1.0.xsd">
    
        <twig:config>
            <!-- ... -->
            <twig:path>%kernel.project_dir%/vendor/acme/foo-bar/templates</twig:path>
        </twig:config>
    </container>
    
  • PHP
    1
    2
    3
    4
    5
    6
    7
    // app/config/config.php
    $container->loadFromExtension('twig', array(
        // ...
        'paths' => array(
           '%kernel.project_dir%/vendor/acme/foo-bar/templates' => null,
        ),
    ));
    

Каталоги, определённые в опции paths имеют более высокий приоритет, чем каталоги по умолчанию, определённые Symfony. В примере выше, если щаблон существует в каталоге acme/foo-bar/templates/ внутри каталога кашего приложения vendor/, то он будет использован Symfony.

Если вы предоставите значение для любого пути, Symfony примет его, как пространство имён Twig для этого каталога:

  • YAML
    1
    2
    3
    4
    5
    # app/config/config.yml
    twig:
        # ...
        paths:
            '%kernel.project_dir%/vendor/acme/foo-bar/templates': 'foo_bar'
    
  • XML
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    <!-- app/config/config.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
            http://symfony.com/schema/dic/services/services-1.0.xsd
            http://symfony.com/schema/dic/twig http://symfony.com/schema/dic/twig/twig-1.0.xsd">
    
        <twig:config>
            <!-- ... -->
            <twig:path namespace="foo_bar">%kernel.project_dir%/vendor/acme/foo-bar/templates</twig:path>
        </twig:config>
    </container>
    
  • PHP
    1
    2
    3
    4
    5
    6
    7
    # app/config/config.php
    $container->loadFromExtension('twig', array(
        // ...
        'paths' => array(
           '%kernel.project_dir%/vendor/acme/foo-bar/templates' => 'foo_bar',
        ),
    ));
    

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

1
@foo_bar/template_name.html.twig

strict_variables

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

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

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