在 Twig 模板中检测和检查变量

03/10/2025, by Ivan

在处理 Twig 模板文件时，大多数变量都会在模板文件的注释中进行说明。然而，当情况并非如此，或者主题或模块引入了新变量时，我们需要一种方法来检测模板中可用的所有变量。Twig 提供了 dump() 函数来检测和检查模板文件中的变量。

如果未启用调试，dump() 函数将不会输出任何内容。了解如何启用 Twig 调试。

启用后，dump() 函数可以用来在模板中输出某个变量或多个变量的信息。

检查单个变量

如果你的模板中有一个标题变量，以下代码会将其内容输出到模板中：

{{ dump(title) }}

检测模板中所有可用的变量

要输出模板中所有可用的变量及其内容，请在模板中添加以下内容（需要先启用调试）：

{{ dump() }}

若只想输出可用变量的键名，请使用：

{{ dump(_context|keys) }}

在所有 Twig 模板中，还有一些额外的全局变量：

_self 指向当前模板，并包含模板的扩展信息，例如编译后模板类的名称和 Twig 环境信息。_self 已弃用并在 Twig 2.x 版本中被移除。
_context 指向当前上下文，包含所有传递给模板的变量，例如从 theme() 传入的变量、预处理生成的变量或在模板中设置的变量。写 {{ dump() }} 而不指定变量等同于 {{ dump(_context) }}。
_charset 指向当前字符集。

谨慎使用 dump()

如果你想查看所有变量，但 dump() 因递归或类似问题导致内存耗尽，你可以遍历 _context 来查看其中的所有键：

<ol>
  {% for key, value in _context  %}
    <li>{{ key }}</li>
  {% endfor %}
</ol>

然后使用条件检查（例如 {% if loop.index == 2 %}）仅在需要时输出该值。

使用 xdebug 调试

最常推荐的调试方式是使用带有 xdebug 插件的 IDE。

最简单的配置方式是使用 PHPstorm（商业软件）与 xdebug。Microsoft VSCode 是免费的开源 IDE，也有插件能完成同样的事情，而不需要购买商业软件。

使用 xdebug 可以让你逐步执行代码，查看变量内容，以避免 dump 或 kint 使用时可能出现的无限循环问题。

一个名为 twig_xdebug 的小模块可以帮助在 xdebug 中显示可用变量。

使用 kint 调试

Twig 中的 dump() 函数通常会在网页上打印大量文本，使得在信息堆中找到需要的内容变得困难。

kint，一个 PHP 调试工具，是 dump() 的替代方案。kint() 函数的工作方式与 dump() 相同，但它提供了一个可展开/可折叠的界面来展示变量。

Devel 项目提供了 devel kint 模块，使开发人员可以使用 kint() 代替 dump()。

1. 下载 devel 模块。
2. 安装 "devel kint" 模块。
3. 和 dump() 一样，kint() 在未启用调试时不会输出任何内容。了解如何启用 Twig 调试。
4. 在你的 .twig 文件中使用 kint() 检查变量，就像 dump() 中描述的那样。
5. 如有需要，下载并安装 Search Kint 模块，以便在嵌套变量列表中进行搜索。

方法和类白名单策略

在处理对象时，我们通过 TwigSandboxPolicy 将允许调用的 getter 和 setter 方法或对象放入白名单。这是为了防止在模板中调用任意方法。例如：{{ node.delete }} 在节点对象上可能会删除该节点，如果没有白名单保护的话。你可以在 settings.php 文件中添加以下内容来扩展白名单：

$settings['twig_sandbox_whitelisted_methods'] = [
  'id',
  'label',
  'bundle',
  'get',
  '__toString',
  'toString',
  'referencedEntities',
];

其中 'referencedEntities' 就是你想在模板中使用的方法。

额外区块类型 (EBT) - 全新的布局构建器体验❗

❗额外段落类型 (EPT) - 全新的 Paragraphs 体验