Pro 版本

模板

速览

NextPDF\Pro\Template 将一个 JSON 模板定义解析为一个有类型的值对象，并以类型感知的格式化将一个关联数据数组绑定到其占位符。它产出一个结构化的绑定结果；它本身不渲染 PDF。

可用性与授权

此功能随 NextPDF Pro（nextpdf/pro）交付，并以一份 Pro 层级的授权信封激活。没有该权益的部署不会加载此功能的类。除层级授权外，没有额外的运行时能力标志对此模块进行门控。比较各版本并获取授权。

安装

composer require nextpdf/pro:^3

概念概览

一个模板是一个 JSON 文档，描述一个页面设置和一个定位占位符的列表。TemplateParser 验证 JSON 并产出一个不可变的 TemplateDefinition。验证是严格的：它根据一个允许列表检查页面尺寸（A3–A6、B4、B5、Letter、Legal、Tabloid）、 orientation（P 或 L），以及每个占位符的 name、type 与数值坐标，并拒绝重复的占位符 name。

TemplateDataBinder 绑定一个数据数组（与占位符 name 不区分大小写地匹配），并按 PlaceholderType 格式化每个值：

Text / Image / Barcode —— 值作为字符串透传。
Date —— 以占位符的 format（默认 Y-m-d）格式化，接受字符串、Unix 时间戳，或 DateTimeInterface。
Number —— number_format，小数位来自 format（默认 2）。
Currency —— 以 format 字符串作为前缀的格式化数字（默认 $）。
Conditional —— 基于真值性的 "true" 或 "false"。

结果是一个 BindingResult，承载绑定后的值、缺失的必填字段列表，以及任何格式化告警。把绑定后的值转为一份渲染好的 PDF 是调用方的职责，需使用 Core document 与 writer API，以及可选的 backgroundPdf 引用。

为何如此设计

解析器是唯一权威的关口。它把不受信任的 JSON 转为一个不可变、完全有类型的 TemplateDefinition，而绑定随后作为该值的纯函数运行。每个之后会抵达格式化汇点的字段，都在解析时被列入允许列表并做长度约束。页面尺寸、orientation、数字精度以及控制字符都在此处失败，而非在渲染中途。字符串日期会与一组固定的规范格式匹配，因此像 now 或 +1 year 这样的值无法让输出依赖于挂钟时间。本模块刻意在一个 BindingResult 处停止，并把渲染、路径解析以及背景合成留给调用方，这使得信任边界保持显式。

设计背景：发票与电子发票。

行为契约

输入。 一个 JSON 字符串（TemplateParser）和一个数据数组（TemplateDataBinder）。
输出。 解析得到 TemplateDefinition；绑定得到 BindingResult。
验证。 validate() 返回一个人类可读的错误列表，且从不抛出；parse() 在验证失败时抛出 InvalidArgumentException。
缺失数据。 一个没有数据且默认值为空的占位符会被报告在 missingFields 中；一个具有非空默认值的占位符使用该默认值。
确定性。 解析与绑定是其输入的纯函数。

公开 API 范围

Type	Kind	Key members
`NextPDF\Pro\Template\TemplateParser`	`final class`	`parse(string $json): TemplateDefinition`、`validate(string $json): list<string>`
`NextPDF\Pro\Template\TemplateDataBinder`	`final class`	`bind(TemplateDefinition $template, array $data): BindingResult`
`NextPDF\Pro\Template\TemplateDefinition`	`final readonly class`	`string $name`、`string $pageSize`、`string $orientation`、`array $placeholders`、`string $backgroundPdf`、`getPlaceholder(string $name): ?TemplatePlaceholder`、`requiredFields(): list<string>`
`NextPDF\Pro\Template\TemplatePlaceholder`	`final readonly class`	name、`PlaceholderType $type`、坐标、默认值、format
`NextPDF\Pro\Template\BindingResult`	`final readonly class`	`array $bindings`、`array $missingFields`、`array $warnings`
`NextPDF\Pro\Template\PlaceholderType`	`enum`	`Text`、`Image`、`Barcode`、`Date`、`Number`、`Currency`、`Conditional`；`requiresFormatting(): bool`

代码示例 —— 快速上手

<?php

declare(strict_types=1);

use NextPDF\Pro\Template\TemplateDataBinder;
use NextPDF\Pro\Template\TemplateParser;

$json = '{"name":"Invoice","pageSize":"A4","orientation":"P","placeholders":'
 . '[{"name":"total","type":"currency","x":400,"y":700,"width":120,'
 . '"height":18,"format":"$"}]}';

$template = (new TemplateParser())->parse($json);
$result = (new TemplateDataBinder())->bind($template, ['total' => 1299.5]);

foreach ($result->bindings as $bound) {
 echo $bound->placeholder->name, ' => ', $bound->formattedValue, "\n";
}

代码示例 —— 生产环境

<?php

declare(strict_types=1);

use NextPDF\Pro\Template\TemplateDataBinder;
use NextPDF\Pro\Template\TemplateParser;

function bindOrReject(string $json, array $data): array
{
 $parser = new TemplateParser();

 $errors = $parser->validate($json);
 if ($errors !== []) {
 throw new InvalidArgumentException(implode('; ', $errors));
 }

 $template = $parser->parse($json);
 $result = (new TemplateDataBinder())->bind($template, $data);

 if ($result->missingFields !== []) {
 throw new RuntimeException(
 'missing required fields: ' . implode(', ', $result->missingFields),
 );
 }

 return $result->bindings; // hand to the renderer
}

边界情况与注意事项

一个不可解析的日期字符串会产生一个告警，并保留原始字符串，而非抛出。
currency format 字符串被用作一个字面前缀（例如 "$" 或 "EUR "），而非一个区域标识符。
backgroundPdf 是承载在定义上的一个路径引用；本模块不会打开、验证或合成它 —— 那是渲染器的工作。
占位符 name 不区分大小写地匹配；JSON 中重复的 name 是一个验证错误。

性能

解析是一次 JSON 解码加结构性验证；绑定在占位符数量上呈线性。参见 performance_budget。

安全说明

JSON 以 JSON_THROW_ON_ERROR 解码，并在一个 TemplateDefinition 被构造之前根据固定的允许列表验证。本模块执行无文件或网络 I/O；backgroundPdf 路径在此不被解引用，因此路径处理与访问控制属于渲染器。

一致性

本模块没有直接的 PDF 规范层面：它解析一个 JSON 模板并格式化值。Page-size 与 orientation 词汇表是 NextPDF 约定，而非规范性的 PDF 构造。

Core 回退/替代方案

不存在 Core 模板定义层。对于完全命令式的文档构造，请直接使用开源 Core document 与 writer API。参见 /modules/core/document/。

Enterprise 边界说明

本模块定义并绑定模板。它不执行邮件合并（mail-merge）编排、批处理作业调度或渲染；那些关注点超出范围，并由别处处理。

发布边界

本页仅描述外部可观测的行为与受支持的公开 API 范围。内部命名空间路径、辅助类、机制表、运行手册文件名以及工单前缀均超出范围。