TwigBundle配置信息("twig"根键)



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
47
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
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
<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>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
$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_serviceautoescape_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。例如:

1
2
3
4
5
# app/config/config.yml
twig:
    # ...
    paths:
        "%kernel.root_dir%/../vendor/acme/foo-bar/templates": ~
1
2
3
4
5
6
7
8
9
10
11
12
<!-- 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>
1
2
3
4
5
6
7
// 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的命名空间:

1
2
3
4
5
# app/config/config.yml
twig:
    # ...
    paths:
        "%kernel.root_dir%/../vendor/acme/foo-bar/templates": 'foo_bar'
1
2
3
4
5
6
7
8
9
10
11
12
<!-- 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>
1
2
3
4
5
6
7
# 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 发表评论或留下问题(我们会尽量回复)