模板引擎概述 Template Overview

DouPHP 前台与后台的模板，统一由自研的编译式模板引擎 DouView 1.0 渲染，实现位于 core/web/template。它是「先编译成 PHP、再 include 执行」的两段式引擎：模板源文件只在需要时被编译一次，编译产物落盘缓存，后续请求直接执行缓存文件。

本手册是 DouView 的全面使用手册：逐一覆盖所有标签、所有变量、所有修饰器、表达式语法、预过滤器、安全约束，并延伸到主题制作语法。每个标签独立成篇，给出完整语法、全部参数与默认值、编译期行为、边界与安全限制、真实模板示例。

一、编译管线

模板从源文件到最终输出，经历四个阶段：

模板源 → Prefilter（预过滤） → Lexer（词法） → Parser（语法/AST） → CodeGenerator（生成 PHP） → 编译产物
                                                                                          ↓
                                                              include 编译产物 + RenderContext 运行期渲染

• Prefilter 预过滤：编译前对源文本做变换，前台与后台各一套（详见「预过滤器 Prefilter」篇）。
• Lexer 词法：按定界符把源切成「文本块」与「标签块」Token，{literal} 区、注释等在词法层特殊处理。
• Parser 语法：把 Token 组装成 AST（抽象语法树），块标签（{if}/{foreach}/{list}/{category}/{strip}）在此入栈配对。
• CodeGenerator 代码生成：遍历 AST，各 NodeType 由对应标签编译器 emit 成 PHP 片段，最后 assemble() 统一拼装（含 {strip} 空白折叠）。

二、运行期载体 RenderContext（$ctx）

编译产物在运行期只依赖一个对象 $ctx（RenderContext 实例）。模板变量、循环元数据、修饰器分发、子模板包含全部经它访问：

• $ctx->vars：模板变量作用域（与引擎 assign 的数据引用绑定）。
• $ctx->loops / $ctx->loopVarmap：循环运行期数据与 @property 支持。
• $ctx->filter(名, 值, 参数...)：修饰器运行期分发入口。
• $ctx->set()：{assign} 与 {include assign=...} 的写入入口。
• $ctx->includeTemplate()：子模板包含（子作用域隔离）。

业务侧一般不直接接触 DouView，而是通过 \Dou\Core\Facade\View 门面调用（view('xxx.dwt', $data)）。

三、18 种节点类型（NodeType）

Parser 产出的 AST 节点共 18 种，覆盖引擎全部语法能力：

四、引擎配置项

DouView 实例的公开配置（core/web/template/DouView.php）：

五、文件扩展名白名单与命名约定

模板资源名（{include} 的 file、view() 的第一个参数）只允许以下扩展名：

.tpl   .htm   .html   .dwt

DouPHP 的惯例分工：

• .dwt：前台主题页面模板（如 index.dwt、article.dwt）。
• .htm：后台页面模板。
• .tpl：公共片段（如 inc/header.tpl、inc/footer.tpl），用 {include} 引入。

资源名禁止包含 ..、绝对路径或盘符（resolveTemplatePath 会拒绝并做越界校验），详见「模板包含 Include」与「自动转义与安全」篇。

六、阅读指引

• 变量与表达式：见「变量输出 Variable Output」「变量访问语法 Variable Access」「表达式运算 Expressions」。
• 控制结构：见「条件判断 If」「循环遍历 Foreach」「模块列表 List」「分类树 Category」。
• 核心标签：见「路由链接 Url」（最常用、最详尽）「模板包含 Include」等。
• 修饰器与内建变量：见「变量修饰器 Modifiers」「系统变量 Douview」。
• 主题制作：见 G 组「前台通用变量」「主题目录结构」「主题数据装配 Portal」等。