Drupal Twig 转换指南（tpl.php 到 html.twig）
本文档在 Drupal 8 的 Twig 转换过程中大部分时间都被使用过，并且也可能对你在更新自己的主题和模块以使用 Drupal 8 中的 Twig 模板引擎时有所帮助。
注意：所有与 Twig 相关的工作现在都在 Drupal 核心问题队列 中进行。仅使用 Twig 转换沙盒 来查找已转换的模板和函数。
核心贡献者步骤：
- 查找 核心问题，以发布和查看补丁。
- 不要将补丁应用到沙盒。
- 不要为沙盒创建补丁。
- 仅将沙盒用于测试和/或获取之前转换的代码。
- 观看这个 YouTube 视频 以了解该流程。
设置
克隆 Drupal 8.0.x：
git clone -b 8.0.x http://git.drupal.org/project/drupal.git d8
当前工作版本的 Drupal 将被安装到文件夹 “d8” 中（你可以随意命名它）
1. 像往常一样安装 Drupal（使用标准安装配置文件）。
2. 在 services.yml 中将所有 3 个 Twig 参数（debugging、cache、auto_reload）设置为 True。
转换
主题函数
将主题函数转换为模板文件和预处理函数：
1. 确定你的主题函数来源的文件（theme.inc? Core/modules/color/?）
2. 为你的主题函数创建一个 X.html.twig 模板文件：
- 按照规则命名新文件
- 删除函数名前缀 theme_ 并以 .html.twig 结尾
- 将下划线 (“_”) 转换为中划线 (“-”)
- 示例：
* theme_link() → link.html.twig
* theme_user_signature() → user-signature.html.twig
3. 将新的 Twig 模板放入完整主题的 templates 文件夹（在沙盒中）：
- 对于来自某个模块的函数，如 stark/templates/comment
- 对于来自 theme.inc 的函数，放入 stark/templates/theme.inc
- 对于来自 form.inc 的函数，放入 stark/templates/form.inc
4. 转到 Drupal 8 API 文档 并查找你的函数。
- （在这个 电子表格 中有所有函数的链接）
5. 在文件顶部添加 PHP 风格的文档注释，并用 Twig 注释 {# #} 包裹。
- 顶部添加 @file 行。
- 复制函数定义到 @file 下方，并将“返回 HTML ...”改写为“默认主题实现 ...”。保持单行。
- 添加 “可用变量:” 行（替换 @param 变量）。
- 复制 api.drupal.org 文档中 “参数” 部分的变量。
- 删除 @see template_preprocess()，如果存在的话。
- 添加 @see template_preprocess_THEME_HOOK()。
- 添加 @ingroup 注释（参见下面示例）。
6. 在文档块下方复制原始函数代码（见示例）
7. 将主要的 PHP 代码更改为 HTML 和打印语句：
- 从 HTML 中删除 PHP 代码，例如：
* function whatever() { ... return $output; }
- 删除 PHP echo 并改用 {{}}
* $variables['title'] → {{ title }}
* $variables['page']['tabs'] → {{ page.tabs }}
- 用 Twig {% %} 替代 PHP 逻辑：
* <?php foreach $items as $item?> → {% for item in items %}
- 用 {# #} 替代 PHP 注释
- 用 {{ 'text'|t }} 替代 t() 函数
- 将所有 PHP 逻辑转移到预处理函数中。
8. 如果在转换过程中发现可改进的地方，例如合并重复模板或改进标记/变量命名，请在电子表格中记录或在沙盒中提交问题。例如：http://drupal.org/node/180591
转换或合并为预处理函数
注意：
- 预处理函数将取代所有主题函数。
- 如果模板中有 PHP 逻辑影响输出变量，该逻辑必须移到预处理函数。
- 如果模板起始为主题函数，则必须转换为预处理函数。
- 如果某些主题函数已有预处理函数，则变量处理逻辑必须移入预处理函数。
- 不要在 hook_theme 实现中添加指示 Drupal 使用模板文件替代主题函数的行。
说明：
- 将 theme_YOURFUNCTION 改为 template_preprocess_YOURFUNCTION。
- 通过引用传递 $variables，加上 & 符号，例如 theme_select($variables) → template_preprocess_select(&$variables)。
- 函数只保留变量处理逻辑，删除所有输出（$output）。
如果你的 Twig 模板缺少某些函数……
如果你需要在 Twig 模板中使用尚未支持的过滤器或函数，请在这个 公开议题 中添加。请记住，大多数 PHP 或 Drupal 函数应移入预处理函数。只有当主题开发者确实需要时，函数才应留在模板中。
简单转换示例 (theme_link)
PHP 代码
function theme_link($variables) { return '' . ($variables['options']['html'] ? $variables['text'] : check_plain($variables['text'])) . ''; }
Twig 模板 (文件名: link.html.twig)
{# /** * @file * Default theme implementation to display a link. * * Available variables: * - text: The link text for the anchor tag. * - url: The complete URL being linked to, such as * "/node/34" or "http://example.com/foo". * - attributes: Remaining HTML attributes for the containing element. * * @see template_preprocess_link() * * @ingroup themeable */ #} <a href="{{ url }}" class="{{ attributes.class }}"{{ attributes }}>{{ text }}</a>
system.module 中的更改（预处理函数）
/** * Prepares variables for link templates. * * Default template: link.html.twig. * * @param array $variables * An associative array containing: * - text: The translated link text for the anchor tag. * - path: The internal path or external URL being linked to. * - options: An associative array of additional options. */ function template_preprocess_link(&$variables) { $variables['url'] = url($variables['path'], $variables['options']); }
备注：
Andrey Podanenko: http://drupal.org/node/1783130 如何重命名变量
jen: 添加你自己的 Twig 注释标记 {# #}。
jen: 在 Twig 注释中使用标准 PHP doxygen 标记。
jen: 从 api.drupal.org 复制粘贴函数定义。
James Wilson: 从函数复制定义时，将 “返回 HTML ...” 改为 “默认主题实现”。
jen: 从 api.drupal.org 复制粘贴 “参数”。
James Wilson: 删除变量名前的 $ 符号，如果在 doc 块中引用其他变量，使用单引号。参见 http://drupal.org/node/1804710
jen: 使用 {{}} 输出变量。
jen: 属性可以“下钻”，所以可以引用 class 等。
jen: 大多数函数，如 url()，应移出模板并加入预处理。