开发者 Twig

编译缓存

所有模板加载器都可以将编译后的模板缓存在文件系统上以供将来重用。这大大加快了 Twig 的速度，因为模板只编译一次。

内置加载器

以下是内置加载器的列表

1

$loader = new \Twig\Loader\FilesystemLoader($templateDir);

1

$loader = new \Twig\Loader\FilesystemLoader([$templateDir1, $templateDir2]);

1
2

$loader->addPath($templateDir3);
$loader->prependPath($templateDir4);

1

$loader->addPath($templateDir, 'admin');

1

$twig->render('@admin/index.html.twig', []);

1

$loader = new \Twig\Loader\FilesystemLoader('templates', getcwd().'/..');

1
2
3
4
5
6

$loader = new \Twig\Loader\ArrayLoader([
    'index.html.twig' => 'Hello {{ name }}!',
]);
$twig = new \Twig\Environment($loader);

echo $twig->render('index.html.twig', ['name' => 'Fabien']);

1
2
3
4
5
6
7
8
9
10
11

$loader1 = new \Twig\Loader\ArrayLoader([
    'base.html.twig' => '{% block content %}{% endblock %}',
]);
$loader2 = new \Twig\Loader\ArrayLoader([
    'index.html.twig' => '{% extends "base.html.twig" %}{% block content %}Hello {{ name }}{% endblock %}',
    'base.html.twig'  => 'Will never be loaded',
]);

$loader = new \Twig\Loader\ChainLoader([$loader1, $loader2]);

$twig = new \Twig\Environment($loader);

创建您自己的加载器

所有加载器都实现了 \Twig\Loader\LoaderInterface

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

interface \Twig\Loader\LoaderInterface
{
    /**
     * Returns the source context for a given template logical name.
     *
     * @param string $name The template logical name
     *
     * @return \Twig\Source
     *
     * @throws \Twig\Error\LoaderError When $name is not found
     */
    public function getSourceContext($name);

    /**
     * Gets the cache key to use for the cache for a given template name.
     *
     * @param string $name The name of the template to load
     *
     * @return string The cache key
     *
     * @throws \Twig\Error\LoaderError When $name is not found
     */
    public function getCacheKey($name);

    /**
     * Returns true if the template is still fresh.
     *
     * @param string    $name The template name
     * @param timestamp $time The last modification time of the cached template
     *
     * @return bool    true if the template is fresh, false otherwise
     *
     * @throws \Twig\Error\LoaderError When $name is not found
     */
    public function isFresh($name, $time);

    /**
     * Check if we have the source code of a template, given its name.
     *
     * @param string $name The name of the template to check if we can load
     *
     * @return bool    If the template source code is handled by this loader or not
     */
    public function exists($name);
}

如果当前的缓存模板仍然新鲜，则 isFresh() 方法必须返回 true，给定上次修改时间，否则返回 false。

getSourceContext() 方法必须返回 \Twig\Source 的实例。

核心扩展

core 扩展定义了 Twig 的所有核心功能

• 标签;
• 过滤器;
• 函数;
• 测试.

Escaper 扩展

escaper 扩展为 Twig 添加了自动输出转义。它定义了一个标签 autoescape 和一个过滤器 raw。

创建 escaper 扩展时，您可以打开或关闭全局输出转义策略

1
2

$escaper = new \Twig\Extension\EscaperExtension('html');
$twig->addExtension($escaper);

如果设置为 html，则模板中的所有变量都将被转义（使用 html 转义策略），除了那些使用 raw 过滤器的变量

1

{{ article.to_html|raw }}

您也可以通过使用 autoescape 标签在本地更改转义模式

1
2
3
4
5

{% autoescape 'html' %}
    {{ var }}
    {{ var|raw }}      {# var won't be escaped #}
    {{ var|escape }}   {# var won't be double-escaped #}
{% endautoescape %}

转义规则的实现如下

• 在模板中直接用作变量或过滤器参数的文字（整数、布尔值、数组等）永远不会自动转义

  1
  2
  3
  4

  {{ "Twig<br/>" }} {# won't be escaped #}
  
  {% set text = "Twig<br/>" %}
  {{ text }} {# will be escaped #}

• 结果是文字或标记为安全的变量的表达式永远不会自动转义

  1
  2
  3
  4
  5
  6
  7
  8

  {{ any_value ? "Twig<br/>" : "<br/>Twig" }} {# won't be escaped #}
  
  {% set text = "Twig<br/>" %}
  {{ true ? text : "<br/>Twig" }} {# will be escaped #}
  {{ false ? text : "<br/>Twig" }} {# won't be escaped #}
  
  {% set text = "Twig<br/>" %}
  {{ any_value ? text|raw : "<br/>Twig" }} {# won't be escaped #}

• 具有 __toString 方法的对象被转换为字符串并转义。您可以通过 EscaperExtension::addSafeClass() 将某些类和/或接口标记为对某些策略是安全的

  1
  2
  3
  4
  5
  6
  7
  8
  9
  10
  11

  // mark objects of class "HtmlGenerator" as safe for the HTML strategy
  $escaper->addSafeClass('HtmlGenerator', ['html']);
  
  // mark objects of interface "HtmlGeneratorInterface" as safe for the HTML strategy
  $escaper->addSafeClass('HtmlGeneratorInterface', ['html']);
  
  // mark objects of class "HtmlGenerator" as safe for the HTML and JS strategies
  $escaper->addSafeClass('HtmlGenerator', ['html', 'js']);
  
  // mark objects of class "HtmlGenerator" as safe for all strategies
  $escaper->addSafeClass('HtmlGenerator', ['all']);

• 转义在打印之前应用，在应用任何其他过滤器之后应用

  1

  {{ var|upper }} {# is equivalent to {{ var|upper|escape }} #}

• raw 过滤器应仅在过滤器链的末尾使用

  1
  2
  3

  {{ var|raw|upper }} {# will be escaped #}
  
  {{ var|upper|raw }} {# won't be escaped #}

• 如果链中的最后一个过滤器被标记为对当前上下文安全（例如，html 或 js），则不应用自动转义。escape 和 escape('html') 被标记为对 HTML 安全，escape('js') 被标记为对 JavaScript 安全，raw 被标记为对所有内容安全。

  1
  2
  3
  4
  5

  {% autoescape 'js' %}
      {{ var|escape('html') }} {# will be escaped for HTML and JavaScript #}
      {{ var }} {# will be escaped for JavaScript #}
      {{ var|escape('js') }} {# won't be double-escaped #}
  {% endautoescape %}

Sandbox 扩展

sandbox 扩展可用于评估不受信任的代码。在 Twig Sandbox 章节中阅读更多相关信息。

Profiler 扩展

profiler 扩展为 Twig 模板启用了一个 profiler；它应该仅在您的开发机器上使用，因为它会增加一些开销

1
2
3
4
5

$profile = new \Twig\Profiler\Profile();
$twig->addExtension(new \Twig\Extension\ProfilerExtension($profile));

$dumper = new \Twig\Profiler\Dumper\TextDumper();
echo $dumper->dump($profile);

一个 profile 包含有关模板、块和宏执行的时间和内存消耗的信息。

您也可以以 Blackfire.io 兼容的格式转储数据

1
2

$dumper = new \Twig\Profiler\Dumper\BlackfireDumper();
file_put_contents('/path/to/profile.prof', $dumper->dump($profile));

上传 profile 以可视化它（首先创建一个 免费帐户）

1

blackfire --slot=7 upload /path/to/profile.prof

Optimizer 扩展

optimizer 扩展在编译之前优化节点树

1

$twig->addExtension(new \Twig\Extension\OptimizerExtension());

默认情况下，所有优化都已启用。您可以通过将它们传递给构造函数来选择要启用的优化

1
2
3

$optimizer = new \Twig\Extension\OptimizerExtension(\Twig\NodeVisitor\OptimizerNodeVisitor::OPTIMIZE_FOR);

$twig->addExtension($optimizer);

Twig 支持以下优化

• \Twig\NodeVisitor\OptimizerNodeVisitor::OPTIMIZE_ALL，启用所有优化（这是默认值）。
• \Twig\NodeVisitor\OptimizerNodeVisitor::OPTIMIZE_NONE，禁用所有优化。这减少了编译时间，但可能会增加执行时间和消耗的内存。
• \Twig\NodeVisitor\OptimizerNodeVisitor::OPTIMIZE_FOR，通过在可能的情况下删除 loop 变量创建来优化 for 标签。