Template — 深入參考

速覽

本深入參考記錄所接受的 JSON 範本結構描述、每一條驗證規則，以及資料綁定器各型別精確的格式化行為。此模組會解析範本定義，然後將呼叫端的資料綁定到具型別的 placeholder。它發射的是格式化後的字串；它並不繪製 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	不分大小寫比對 placeholder 並依型別格式化	BindingResult	絕不拋出；異常會轉為警告或缺漏欄位	鍵不存在時使用 placeholder 的預設值。
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	無	收集沒有預設值的 placeholder 名稱	list<string>	不會失敗	非空的預設值代表該 placeholder 為選用。
TemplatePlaceholder::__construct	string $name, PlaceholderType $type, float $x, float $y, float $width, float $height, string $defaultValue = '', string $format = ''	儲存單一 placeholder 區域	TemplatePlaceholder	引數型別不符時拋出 TypeError	座標為自左上角起算的點（point）。
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	無	計算成功綁定的 placeholder 數量	int	不會失敗	—
BoundPlaceholder::__construct	TemplatePlaceholder $placeholder, string $formattedValue, mixed $rawValue	將 placeholder 與其格式化值配對	BoundPlaceholder	引數型別不符時拋出 TypeError	final readonly 值物件。
PlaceholderType	列舉案例 Text、Image、Barcode、Date、Number、Currency、Conditional	以字串為底的 placeholder 分類	列舉實例	未知值時由 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，或一個非陣列的值。
• 每個 placeholder：缺漏或空白的名稱、無效的型別、缺漏或非數值的 x、y、width、height、重複名稱（不分大小寫）。
• defaultValue：非字串、長度超過 4096 位元組，或帶有 ASCII 控制字元。
• format：非字串、長度超過 256 位元組，或帶有 ASCII 控制字元。
• number placeholder 的 format 不是非負整數，或超過 30。

綁定語意（TemplateDataBinder::bind）：

• 資料鍵會轉為小寫，以便與 placeholder 名稱進行不分大小寫的比對。
• 鍵不存在但具非空預設值時綁定該預設值；鍵不存在且無預設值時會列入 missingFields。
• Text、image、barcode 值會原樣轉型為字串。
• 日期綁定接受 DateTimeInterface、整數 Unix 時間戳記，或四種明確格式之一的字串。預設輸出格式為 Y-m-d。
• 數字綁定使用 number_format(value, decimals, '.', ',')。小數位數來自 format，預設為 2，並限定於 0 至 30 的範圍。
• 貨幣綁定會以 format 作為前綴加在格式化後的數字之前，前綴預設為 $。
• Conditional 綁定會由布林轉型發射 "true" 或 "false"。

邊界案例與失敗模式

• backgroundPdf 從不會被本模組開啟或解參考。它是一個交給彩現器的不透明字串。
• 綁定到 Number 或 Currency placeholder 的非數值會產生一個警告；該值會被字串轉型，而非被拒絕。
• 日期字串採嚴格解析。相對與自然語言的詞元 （「now」、「+1 year」、「tomorrow」）不符合任何接受的格式，因此會發出警告，且原始值原樣通過而不變。
• 整數日期值會透過 @ epoch 形式讀為 Unix 時間戳記。
• 抵達綁定器的 Number format 精度落在 0 至 30 之外時會發出警告並拒絕；綁定器退回至預設精度 2。
• 本模組不發生任何密碼學運算，因此沒有任何 FIPS 模式特定的行為。

一致性

不存在直接的 PDF 規範範圍。頁面尺寸與方向的詞彙是 NextPDF 慣例，且本模組發射的是格式化後的值， 而非 PDF 物件。嚴格的字串日期允許清單接受 RFC 3339 §5.6 所定義的 ISO 8601 網際網路日期/時間設定檔，以及一個 Y-m-d 日曆日期與兩種本地日期時間形式。NextPDF 記錄了讀取這些格式的能力；它並不主張取得任何針對 RFC 3339 或 ISO 8601 的認證。

開發備註

• TemplateParser 與 TemplateDataBinder 皆為無狀態。單一實例可重複使用，並可安全地跨綁定共享。
• 四個值物件皆為 final readonly；針對生產輸入，請透過解析器來建構它們，而非手動建構。
• validate 會單次遍歷回報每一個結構錯誤，而 parse 會先呼叫 validate，並在匯總訊息上拋出。表單式回饋請用 validate， 快速失敗式的擷取請用 parse。
• 長度與精度界限在解析器作為權威閘門強制執行。 TemplateDataBinder 會再次檢查數字精度，作為對抗 number_format 記憶體放大的接收端防護。

出版邊界

本頁僅記錄外部可觀察的行為與受支援的公開 API 介面。內部命名空間路徑、輔助類別、機制表、runbook 檔名，以及 ticket 前綴皆不在範圍內。

另請參閱

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