Twig 配置参考 (TwigBundle)

编辑此页

TwigBundle 将 Twig 库集成到 Symfony 应用程序中，以渲染模板。所有这些选项都在应用程序配置的 twig 键下配置。

        1
2
3
4
5
        # displays the default config values defined by Symfony
$ php bin/console config:dump-reference twig

# displays the actual config values used by your application
$ php bin/console debug:config twig
    

提示

当使用 XML 时，你必须使用 https://symfony.ac.cn/schema/dic/twig 命名空间，相关的 XSD 模式可在以下位置找到：https://symfony.ac.cn/schema/dic/twig/twig-1.0.xsd

配置

auto_reload

类型：boolean 默认值：%kernel.debug%

如果 true，每当渲染模板时，Symfony 首先检查自模板编译以来其源代码是否已更改。如果已更改，则会自动重新编译模板。

autoescape_service

类型：string 默认值：null

默认应用于模板的转义策略（以防止 XSS 攻击）在编译时根据模板的文件名确定。这意味着，例如，*.html.twig 模板的内容将针对 HTML 进行转义，而 *.js.twig 的内容将针对 JavaScript 进行转义。

此选项允许定义 Symfony 服务，该服务将用于确定应用于模板的默认转义。

autoescape_service_method

类型：string 默认值：null

如果定义了 autoescape_service 选项，则此选项定义了用于确定应用于模板的默认转义的方法。

如果在 autoescape_service 中定义的服务是可调用的（即，它定义了 `__invoke() PHP magic method`_），则可以省略此选项。

base_template_class

类型：string 默认值：Twig\Template

7.1

base_template_class 选项自 Symfony 7.1 起已弃用。

Twig 模板在使用它们渲染内容之前被编译成 PHP 类。此选项定义了所有模板类从中扩展的基类。不鼓励使用自定义基模板，因为它会使你的应用程序更难以维护。

cache

类型：string | false 默认值：%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 过滤器在显示值时使用的格式，当没有将特定格式作为参数传递时。

interval_format

类型：string 默认值：%d days

date 过滤器在显示 DateInterval 实例时使用的格式，当没有将特定格式作为参数传递时。

timezone

类型：string 默认值：（date_default_timezone_get() 返回的值）

使用 date 过滤器格式化日期值时使用的时区，并且没有将特定时区作为参数传递时。

debug

类型：boolean 默认值：%kernel.debug%

如果 true，则编译后的模板包含一个 __toString() 方法，该方法可用于显示其节点。

此选项还控制 Twig dump 工具的行为。如果此选项为 false，则 dump() 函数不会输出任何内容。

default_path

类型：string 默认值：%kernel.project_dir%/templates

Symfony 默认查找应用程序 Twig 模板的目录路径。如果将模板存储在多个目录中，请同时使用 paths 选项。

file_name_pattern

类型：string 或 string 的 array 默认值：[]

某些应用程序将其前端资源存储在与 Twig 模板相同的目录中。lint:twig 命令会过滤这些文件，以仅 lint 那些与 *.twig 文件名模式匹配的文件。

但是，cache:warmup 命令会尝试编译所有文件，包括非 Twig 模板（并且它会忽略编译错误）。结果是不必要的 CPU 和磁盘资源消耗。

在这些情况下，使用此选项定义作为 Twig 模板的文件的文件名模式（其余文件将被 cache:warmup 忽略）。此选项的值可以是正则表达式、glob 或字符串

        1
2
3
4
        # config/packages/twig.yaml
twig:
    file_name_pattern: ['*.twig', 'specific_file.html']
    # ...
    

        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="https://symfony.ac.cn/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:twig="https://symfony.ac.cn/schema/dic/twig"
    xsi:schemaLocation="https://symfony.ac.cn/schema/dic/services
        https://symfony.ac.cn/schema/dic/services/services-1.0.xsd
        https://symfony.ac.cn/schema/dic/twig https://symfony.ac.cn/schema/dic/twig/twig-1.0.xsd">

    <twig:config>
        <twig:file-name-pattern>*.twig</twig:file-name-pattern>
        <twig:file-name-pattern>specific_file.html</twig:file-name-pattern>
        <!-- ... -->
    </twig:config>
</container>
    

        1
2
3
4
5
6
7
8
9
10
11
        // config/packages/twig.php
use Symfony\Config\TwigConfig;

return static function (TwigConfig $twig): void {
    $twig->fileNamePattern([
        '*.twig',
        'specific_file.html',
    ]);

    // ...
};
    

form_themes

类型：string 的 array 默认值：['form_div_layout.html.twig']

定义一个或多个应用于应用程序所有表单的表单主题

        1
2
3
4
        # config/packages/twig.yaml
twig:
    form_themes: ['bootstrap_5_layout.html.twig', 'form/my_theme.html.twig']
    # ...
    

        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="https://symfony.ac.cn/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:twig="https://symfony.ac.cn/schema/dic/twig"
    xsi:schemaLocation="https://symfony.ac.cn/schema/dic/services
        https://symfony.ac.cn/schema/dic/services/services-1.0.xsd
        https://symfony.ac.cn/schema/dic/twig https://symfony.ac.cn/schema/dic/twig/twig-1.0.xsd">

    <twig:config>
        <twig:form-theme>bootstrap_5_layout.html.twig</twig:form-theme>
        <twig:form-theme>form/my_theme.html.twig</twig:form-theme>
        <!-- ... -->
    </twig:config>
</container>
    

        1
2
3
4
5
6
7
8
9
10
11
        // config/packages/twig.php
use Symfony\Config\TwigConfig;

return static function (TwigConfig $twig): void {
    $twig->formThemes([
        'bootstrap_5_layout.html.twig',
        'form/my_theme.html.twig',
    ]);

    // ...
};
    

定义主题的顺序很重要，因为每个主题都会覆盖所有先前的主题。当渲染其块未在表单主题中定义的表单字段时，Symfony 会回退到先前的主题，直到第一个主题。

这些全局主题应用于所有表单，甚至包括使用 form_theme Twig 标签的表单，但你可以为特定表单禁用全局主题。

globals

类型：array 默认值：[]

它定义了自动注入到所有 Twig 模板中的全局变量。了解有关Twig 全局变量的更多信息。

mailer

html_to_text_converter

类型：string 默认值：````

实现 HtmlToTextConverterInterface 的服务，当未明确定义时，该服务将用于从电子邮件的 HTML 内容自动创建文本部分。

number_format

这些选项定义了 number_format 过滤器用于格式化数值的默认值。它们对于避免在每次 number_format 过滤器调用时传递相同的参数很有用。

decimals

类型：integer 默认值：0

当没有将特定数字作为参数传递给 number_format 过滤器时，用于格式化数值的小数位数。

decimal_point

类型：string 默认值：.

当没有将特定字符作为参数传递给 number_format 过滤器时，用于分隔数值的小数部分和整数部分的字符。

thousands_separator

类型：string 默认值：,

当没有将特定字符作为参数传递给 number_format 过滤器时，用于分隔数值中每千位分组的字符。

optimizations

类型：integer 默认值：-1

Twig 包含一个名为 optimizer 的扩展，该扩展在 Symfony 应用程序中默认启用。此扩展分析模板以在编译时对其进行优化。例如，如果你的模板在 for 标记内没有使用特殊的 loop 变量，则此扩展会删除该未使用变量的初始化。

默认情况下，此选项为 -1，这意味着所有优化都已启用。将其设置为 0 以禁用所有优化。你甚至可以选择性地启用或禁用这些优化，如 Twig 文档中关于 optimizer 扩展中所述。

paths

类型：array 默认值：null

定义除了 default_path 选项中定义的目录之外，应用程序模板存储在其中的目录

        1
2
3
4
5
6
        # config/packages/twig.yaml
twig:
    # ...
    paths:
        'email/default/templates': ~
        'backend/templates': 'admin'
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
        <!-- config/packages/twig.xml -->
<container xmlns="https://symfony.ac.cn/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:twig="https://symfony.ac.cn/schema/dic/twig"
    xsi:schemaLocation="https://symfony.ac.cn/schema/dic/services
        https://symfony.ac.cn/schema/dic/services/services-1.0.xsd
        https://symfony.ac.cn/schema/dic/twig https://symfony.ac.cn/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>
    

        1
2
3
4
5
6
7
8
9
        // config/packages/twig.php
use Symfony\Config\TwigConfig;

return static function (TwigConfig $twig): void {
    // ...

    $twig->path('email/default/templates', null);
    $twig->path('backend/templates', 'admin');
};
    

阅读有关模板目录和命名空间的更多信息。

strict_variables

类型：boolean 默认值：%kernel.debug%

如果设置为 true，则当 Twig 变量、属性或方法不存在时，Symfony 会显示异常。如果设置为 false，则会忽略这些错误，并且不存在的值将替换为 null。

本作品，包括代码示例，根据 Creative Commons BY-SA 3.0 许可获得许可。

版本