Template — 深度参考

速览

本深度参考记录了所接受的 JSON 模板 schema、每一条验证规则，以及数据绑定器各类型确切的格式化行为。该模块解析一份模板定义，然后将调用方数据绑定到类型化的占位符上。它发出格式化后的字符串，不绘制 PDF 对象。

可用性与授权

此能力随 NextPDF Pro（nextpdf/pro）发布，并通过 Pro 级授权信封激活。缺少该授权的部署不会加载此能力的类。没有任何运行时能力标志对此模块进行门控。比较各版本并获取授权。

公开 API 范围

该模块暴露两个入口点服务与四个不可变值对象。 以下每个符号都是公开且稳定的。

符号	参数	默认行为	返回	抛出或失败于	备注
TemplateParser::parse	string $json	先验证，再构建定义	TemplateDefinition	存在任何验证错误时抛出 InvalidArgumentException	先委托给 validate。
TemplateParser::validate	string $json	单遍收集所有结构性错误	list<string>（有效时为空）	从不抛出；JSON 解码失败会作为一条消息返回	长度与精度界限的权威关卡。
TemplateDataBinder::bind	TemplateDefinition $template, array<string,mixed> $data	不区分大小写地匹配占位符并按类型格式化	BindingResult	从不抛出；异常会转为告警或缺失字段	键不存在时使用占位符的默认值。
TemplateDefinition::__construct	string $name, string $pageSize, string $orientation, list<TemplatePlaceholder> $placeholders, string $backgroundPdf = ''	存储解析后的定义	TemplateDefinition	参数类型不匹配时抛出 TypeError	final readonly 值对象。
TemplateDefinition::getPlaceholder	string $name	按名称不区分大小写查找	TemplatePlaceholder|null	无失败；不存在时返回 null	—
TemplateDefinition::requiredFields	无	收集没有默认值的占位符名称	list<string>	无失败	非空默认值将占位符标记为可选。
TemplatePlaceholder::__construct	string $name, PlaceholderType $type, float $x, float $y, float $width, float $height, string $defaultValue = '', string $format = ''	存储一个占位符区域	TemplatePlaceholder	参数类型不匹配时抛出 TypeError	坐标为自左上角起算的点值。
TemplatePlaceholder::matches	string $key	不区分大小写的名称比较	bool	无失败	—
BindingResult::__construct	list<BoundPlaceholder> $bindings, list<string> $missingFields, list<string> $warnings	存储绑定结果	BindingResult	参数类型不匹配时抛出 TypeError	final readonly 值对象。
BindingResult::isComplete	无	报告是否每个必填字段都已绑定	bool	无失败	当 missingFields 为空时为真。
BindingResult::count	无	统计成功绑定的占位符数量	int	无失败	—
BoundPlaceholder::__construct	TemplatePlaceholder $placeholder, string $formattedValue, mixed $rawValue	将一个占位符与其格式化值配对	BoundPlaceholder	参数类型不匹配时抛出 TypeError	final readonly 值对象。
PlaceholderType	enum 分支 Text、Image、Barcode、Date、Number、Currency、Conditional	字符串支撑的占位符分类	enum 实例	from() 遇未知值时抛出 ValueError	tryFrom() 改为返回 null。
PlaceholderType::requiresFormatting	无	报告该类型是否消费格式字符串	bool	无失败	对 Date、Number、Currency 为真。

final class TemplateParser
{
    public function parse(string $json): TemplateDefinition;
    public function validate(string $json): array;
}

final class TemplateDataBinder
{
    public function bind(TemplateDefinition $template, array $data): BindingResult;
}

行为契约

所接受的 JSON 结构：

{
  "name": "string (required, non-empty)",
  "pageSize": "A3|A4|A5|A6|B4|B5|Letter|Legal|Tabloid",
  "orientation": "P|L",
  "backgroundPdf": "optional path string",
  "placeholders": [
    { "name": "string", "type": "text|image|barcode|date|number|currency|conditional",
      "x": number, "y": number, "width": number, "height": number,
      "defaultValue": "optional", "format": "optional" }
  ]
}

验证规则，全部由 validate 以消息形式呈现，并由 parse 汇聚为单个异常：

• 缺失或为空的 name。
• pageSize 不在允许列表内，或 orientation 既非 P 也非 L。
• 缺失 placeholders，或其值非数组。
• 每个占位符：缺失或为空的 name；无效的 type；缺失或非数值的 x、y、width、height；重复的 name（不区分大小写）。
• defaultValue：非字符串、长于 4096 字节，或携带 ASCII 控制字符。
• format：非字符串、长于 256 字节，或携带 ASCII 控制字符。
• number 占位符的 format 不是非负整数，或超过 30。

绑定语义（TemplateDataBinder::bind）：

• 数据键被转为小写，以便与占位符名称进行不区分大小写的匹配。
• 缺失的键若带有非空默认值则绑定该默认值；缺失的键若无默认值则记入 missingFields。
• Text、image、barcode 值原样转换为字符串。
• 日期绑定接受 DateTimeInterface、整数 Unix 时间戳，或四种明确格式之一的字符串。默认输出格式为 Y-m-d。
• 数字绑定使用 number_format(value, decimals, '.', ',')。小数位数来自 format，默认为 2，并限定在 0 到 30 的范围内。
• Currency 绑定以 format 作为前缀加在格式化后的数字之前， 前缀默认为 $。
• Conditional 绑定由布尔转换发出 "true" 或 "false"。

边界情况与失败模式

• 本模块从不打开或解引用 backgroundPdf。它是一个交给渲染器的不透明字符串。
• 绑定到 Number 或 Currency 占位符的非数值会产生一个告警；该值被字符串转换，而非被拒绝。
• 日期字符串被严格解析。相对与自然语言词元 （“now”、“+1 year”、“tomorrow”）不匹配任何接受的格式，因此会告警， 原始值原样透传。
• 整数日期值经由 @ 纪元形式被读作 Unix 时间戳。
• 到达绑定器的、落在 0 到 30 之外的 Number format 精度会以告警拒绝；绑定器回退到默认精度 2。
• 本模块中不发生任何密码学操作，因此没有 FIPS-mode 特定行为。

一致性

不存在直接的 PDF 规范层面。Page-size 与 orientation 词汇表是 NextPDF 约定，且本模块发出格式化后的值， 而非 PDF 对象。严格的字符串日期允许列表接受 RFC 3339 §5.6 所定义的 ISO 8601 互联网日期/时间 profile， 以及一种 Y-m-d 日历日期和两种本地日期-时间形式。NextPDF 记录了读取这些格式的能力；它不声称针对 RFC 3339 或 ISO 8601 的任何认证。

开发说明

• TemplateParser 与 TemplateDataBinder 是无状态的。单个实例可复用，并可安全地跨绑定共享。
• 这四个值对象是 final readonly；对生产输入应通过解析器构造它们，而非手工构造。
• validate 单遍报告每一条结构性错误，而 parse 先调用 validate，并在汇聚后的消息上抛出。对表单式反馈使用 validate， 对快速失败式摄取使用 parse。
• 长度与精度界限在解析器处作为权威关卡强制执行。 TemplateDataBinder 在汇点侧重新检查数字精度， 以防范 number_format 的内存放大。

发布边界

本页仅记录外部可观测的行为与受支持的公开 API 范围。内部命名空间路径、辅助类、机制表、runbook 文件名，以及工单前缀均不在范围内。

另请参阅

• Template（能力指南）
• Toc
• Merge