Twig nl2br 过滤器详解：HTML 换行转换与自动转义的前置转义机制

• 后端

本文以 Twig 官方文档中的nl2br过滤器为切入点，完整讲解其在模板中的用法与行为边界，并结合本仓库源码深入剖析其背后的两个关键机制：pre_escape前置转义与is_safe安全标记如何协同工作，保证含 HTML 标签的输出既正确渲染又不引入 XSS 风险。读完本文，你可以准确预测nl2br对换行、空值、危险输入的处理结果，并理解 Twig 自动转义体系中"先转义输入、再标记输出"的通用设计。

基础用法

nl2br过滤器的作用非常直接：在字符串中的每个换行符前插入一个 HTML 换行标签，即 PHP 内置函数nl2br()的行为。官方文档给出的基本示例如下：

{{ "I like Twig.\nYou will like it too."|nl2br }} {# 输出 I like Twig.<br /> You will like it too. #}

一个典型的实战场景是把后台保存的纯文本（如文章内容、用户留言）直接渲染到页面中：用户输入的换行在纯文本里只是\n字符，在 HTML 中默认不产生视觉换行，套用nl2br之后每个段落边界都会变成<br />，文本的原始排版得以保留。

需要注意的是，Twig 的nl2br是"在换行前插入<br />"，换行符本身会被保留。这一细节在本仓库的集成测试 nl2br.test 中得到明确验证：

{{ "I like Twig.\nYou will like it too.\n\nEverybody like it!"|nl2br }}

期望输出为：

I like Twig.<br /> You will like it too.<br /> <br /> Everybody like it!

可以看到：

• 单个\n变成<br />加一个保留的换行符；
• 连续两个\n（空行）产生两行，每行各有一个<br />，视觉上形成一个空段落；
• 这与"先替换\n再插入标签"的实现不同，对渲染结果没有影响，但解释了为什么在源码层面它是纯插入式操作。

对空值与空字符串的处理

测试用例中还覆盖了两个边界输入（见 nl2br.test 第 6～7 行）：

*{{ ''|nl2br }}* *{{ null|nl2br }}*

两者的期望输出都是**，即过滤器对空字符串和null都返回空字符串，不会抛出异常。这在源码中可以直接确认——CoreExtension.php 中的实现只有两行：

/** * Inserts HTML line breaks before all newlines in a string. * * @param string|null $string */ public static function nl2br($string): string { return nl2br($string ?? ''); }

$string ?? ''表明过滤器声明接受string|null参数，空值被归一化为空字符串后再委托给 PHP 内置的nl2br()。因此模板中写{{ text|nl2br }}时，即使text未定义（解析为null）也不会报错，只是输出为空。

过滤器注册：pre_escape与is_safe两个关键选项

nl2br并非简单的"一个函数 + 一个名字"，它的注册声明（CoreExtension.php）携带了两个对安全模型至关重要的选项：

new TwigFilter('nl2br', [self::class, 'nl2br'], ['pre_escape' => 'html', 'is_safe' => ['html']]),

• pre_escape => 'html'：声明该过滤器希望输入在到达回调函数之前先按 HTML 转义一次。这正是官方文档（nl2br.rst）末尾 note 强调的内容——"nl2brfilter pre-escapes the input before applying the transformation"。
• is_safe => ['html']：声明过滤器的输出对 HTML 格式是"安全的"，即输出中包含<br />标签是有意为之的，最终打印时不再被自动转义。

两个选项配合起来形成了一个闭环：输入先转义，避免用户数据中的<script>等标签被原样带进输出；输出标记安全，保证<br />本身不被二次转义成<br />。缺了前半段会引入 XSS 风险，缺了后半段则过滤器完全失效（输出变成字面的<br />文本）。

文档中的 note 可以通过测试用例直观验证（nl2br.test）：

{{ text|nl2br }} {# 数据： text = "If you have some <strong>HTML</strong>\nit will be escaped." #}

期望输出：

If you have some &lt;strong&gt;HTML&lt;/strong&gt;<br /> it will be escaped.

输入里的<strong>被前置转义成了<strong>，而换行处插入的<br />保持原样——前置转义与输出安全标记各自生效、互不干扰。

源码剖析：前置转义在何处发生

"前置转义"不是在执行nl2br回调时做的，而是发生在模板编译阶段，由 EscaperNodeVisitor 在遍历 AST 时改写节点实现：

private function preEscapeFilterNode(FilterExpression $filter, Environment $env): FilterExpression { if ($filter->hasAttribute('twig_callable')) { $type = $filter->getAttribute('twig_callable')->getPreEscape(); } else { // legacy $name = $filter->getNode('filter', false)->getAttribute('value'); $type = $env->getFilter($name)->getPreEscape(); } if (null === $type) { return $filter; } /** @var AbstractExpression $node */ $node = $filter->getNode('node'); if ($this->isSafeFor($type, $node, $env)) { return $filter; } $filter->setNode('node', $this->getEscaperFilter($env, $type, $node)); return $filter; }

从这段代码可以读出三个实现细节：

1. 前置转义是编译期优化，零运行时开销。访问器在leaveNode中拦截所有FilterExpression（EscaperNodeVisitor.php），若过滤器声明了pre_escape类型，就直接把被过滤的表达式节点替换成"先套一个 escape 过滤器"的等价节点。生成的 PHP 代码里就已经是twig_escape(filter($var, 'nl2br'))这样的形式，与运行期无关。
2. 已有安全标记的输入会跳过转义。$this->isSafeFor($type, $node, $env)检查被过滤的表达式是否已对html格式安全（例如Markup实例、或另一个标记了is_safe => ['html']的过滤器输出），若是则不再包裹转义，避免双重转义。
3. 兼容两种注册方式。优先读取新式 first-class callable 上的twig_callable属性（getPreEscape()，见 TwigFilter.php），否则回退到 legacy 的按名字查表路径。

pre_escape选项本身在 TwigFilter 构造函数中默认为null，即大多数过滤器不做前置转义，只有nl2br、spaceless这类会产出 HTML 结构的过滤器才声明它。此外，如果通过 PHP 8 属性注册过滤器（AsTwigFilter 的$preEscape参数），AttributeExtension 会把它映射成同样的'pre_escape'选项，两种注册方式语义完全一致。

对于旧式（函数式）扩展，Resources/core.php 中还保留了 legacy 包装函数：

function twig_nl2br($string) { return CoreExtension::nl2br($string); }

它只是委托给静态方法，行为与属性注册版本一致。

行为总结与实战要点

综合文档、源码与测试，nl2br的完整行为可以归纳为：

实战中几点值得注意：

• nl2br之后不需要再套|raw。它的输出已对 HTML 安全标记，再套raw是冗余的；反过来，也不要把nl2br用在"本来就是安全 HTML"的变量上再期望保留其标签——输入端的 HTML 一律会被转义，这是安全设计而非 bug。
• 前置转义只发生在 HTML 转义上下文中（即autoescape开启或{% autoescape 'html' %}块内），它由转义访问器在编译期插入；若模板整体处于关闭转义的上下文，则不存在二次转义问题。
• 与nl2br同类的"输出 HTML 的过滤器"（如已标记 deprecated 的spaceless）都遵循同样的pre_escape + is_safe组合模式，理解了nl2br，就理解了 Twig 安全模型中这一整类过滤器的工作原理。

参考位置

• 官方文档：nl2br.rst
• 过滤器注册与实现：CoreExtension.php、CoreExtension.php
• 前置转义的编译期实现：EscaperNodeVisitor.php
• 过滤器选项定义：TwigFilter.php、AsTwigFilter.php
• 集成测试：nl2br.test

• 后端