TwigBundle配置信息（"twig"根键）

3.4 版本

维护中的版本

难易度：偏难

twig:
    exception_controller:  twig.controller.exception:showAction

    form_themes:

        # Default: / 默认
        - form_div_layout.html.twig
 
        # Bootstrap:
        - bootstrap_3_layout.html.twig
        - bootstrap_3_horizontal_layout.html.twig
 
        # Foundation / 示例
        - foundation_5_layout.html.twig
 
        # Example: / 示例
        - MyBundle::form.html.twig

    globals:

        # Examples:
        foo:                 '@bar'
        pi:                  3.14
 
        # Example options, but the easiest use is as seen above
        # 样例选项，但最简单的用法是上面那种
        some_variable_name:
            # a service id that should be the value / 服务定义的id作为值
            id:                   ~
            # set to service or leave blank / 设置为服务或留空
            type:                 ~
            value:                ~
    autoescape:                ~
 
    # See 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
                                 # 同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.root_dir%/../vendor/acme/foo-bar/templates": foo_bar

<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="filename"
        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.root_dir%/../vendor/acme/foo-bar/templates</twig:path>
    </twig:config>
</container>

$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'           => 'filename',
     '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.root_dir%/../vendor/acme/foo-bar/templates' => 'foo_bar',
     ),
));

twig.form（XML中的<twig:form />标签）配置键现已不推荐使用，并将在3.0中被移除，使用twig.form_themes选项来代替。

配置 ¶

auto_reload ¶

值选项: boolean 默认值: '%kernel.debug%'

如果设为 true，只要模板被渲染，Symfony就首先检查它的源代码是否自编译之后发生了改变。如果有改变，模板就自动重新编译。

autoescape ¶

值选项: boolean or string 默认值: 'filename'

如果设为 false，自动转义（automatic escaping）将被关闭（你仍然可以在模板中对内容的每一部分进行单独转义）。

本选项被设为false是危险的，会令你的程序在XSS跨站攻击面前变得脆弱，因为多数三方bundle都假设自动转义是开启的，它们不自行对内容进行转义。

如果设成一个字符串，模板内容将使用这个名字所对应的策略进行转义。允许的值有 html, js, css, url, html_attr 以及 filename。默认的值是 filename。这个策略根据文件的扩展名来转义 (比如它使用 html 转义来针对 *.html.twig 模板，而使用 js 转义来针对 *.js.html 模板)。

要定义你自己的转义策略请见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。本选项定义的是基类，所有模板类都要继承于它。使用一个自定义的基础模板（base template）不被提倡，这会令你的程序难于维护。

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)的职责是在不同的错误条件下渲染特定的模板(参考 如何自定义错误页)。修改本选项是高端行为，如果你需要自定义一个错误页，你应该参考此链接。如果你需要针对某异常来执行一些动作，你应该添加一个监听到 kernel.exception 事件 (参考 kernel.event_listener)。

optimizations ¶

值选项: int 默认值: -1

Twig包含了一个被称为optimizer 的扩展，默认在Symfony程序中开启。这个扩展会分析模板，以求在编译时优化它们。例如，你的模板在 for 标签中没有使用特殊的 loop 变量，该扩展将移除这些无用变量的初始化。

默认时，本选项是 -1，这表示全部优化被开启。设为 0 即关闭全部优化。你甚至可以有选择的开启和关闭它们，如同Twig文档中关于 the optimizer extension（optimizer扩展）中所解释的那样。

paths ¶

值选项: array 默认值: null

本选项定义了Symfony所要寻找的Twig模板所在的目录，包括其默认位置 (app/Resources/views/ 以及bundle的 Resources/views/ 目录)。这在对“你的程序所用到的类库或包”中的模板进行整合时是有用的。

paths 选项的值以 key: value 键值对方式定义，其中的 value 部分可以是 null。例如：

# app/config/config.yml
twig:
    # ...
    paths:
        "%kernel.root_dir%/../vendor/acme/foo-bar/templates": ~

<!-- 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.root_dir%/../vendor/acme/foo-bar/templates</twig:path>
    </twig:config>
</container>

// app/config/config.php
$container->loadFromExtension('twig', array(
    // ...
    'paths' => array(
       '%kernel.root_dir%/../vendor/acme/foo-bar/templates' => null,
    ),
));

定义在 paths 选项中的目录相对于Symfony定义的默认目录有更高的优先级。上例，存在于你的程序 vendor/ 文件夹之下 acme/foo-bar/templates/ 目录中的模板，将被Symfony所使用。

如果你提供了任何一个路径值，Symfony都将认为该目录是Twig的命名空间：

# app/config/config.yml
twig:
    # ...
    paths:
        "%kernel.root_dir%/../vendor/acme/foo-bar/templates": 'foo_bar'

<!-- 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.root_dir%/../vendor/acme/foo-bar/templates</twig:path>
    </twig:config>
</container>

# app/config/config.php
$container->loadFromExtension('twig', array(
    // ...
    'paths' => array(
       '%kernel.root_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来替代之。

本文，包括例程代码在内，采用的是 Creative Commons BY-SA 3.0 创作共用授权。

登录symfonychina 发表评论或留下问题（我们会尽量回复）

文章目录

起步

指南

组件

培训

官方技能认证

TwigBundle配置信息（"twig"根键）

配置 ¶

auto_reload ¶

autoescape ¶

autoescape_service ¶

autoescape_service_method ¶

base_template_class ¶

cache ¶

charset ¶

debug ¶

exception_controller ¶

optimizations ¶

paths ¶

strict_variables ¶

Symfony 4.2：cookie安全的自动化 2019-01-22

Symfony 4.2：改进的表单类型扩展（翻译中） 2019-01-22

Symfony 4.2：IntlMessageFormatter 2019-01-22

Symfony3技能认证，现已在全球4000余家考点展开！包括国际考试代理机构的中国考点...

社区

官方博客