Pro 版本

範本

速覽

NextPDF\Pro\Template 會將一份 JSON 範本定義解析為一個具型別的值物件，並以型別感知的格式化將一個關聯式資料陣列綁定至其 placeholder。它會產生一個結構化的綁定結果；它本身不會彩現一份 PDF。

可用性與授權

此功能隨 NextPDF Pro（nextpdf/pro）出貨，並以 Pro 層級的授權封裝啟用。缺乏該權利的部署不會載入此功能的類別。除了層級授權之外，沒有其他執行階段能力旗標會對此模組進行閘控。比較各版本並取得授權。

安裝

composer require nextpdf/pro:^3

概念總覽

一份範本是一份 JSON 文件，描述一個頁面設定與一個定位 placeholder 的清單。TemplateParser 會驗證 JSON 並產生一個不可變的 TemplateDefinition。驗證是嚴格的：它會對照一個允許清單檢查頁面尺寸（A3–A6、B4、B5、Letter、Legal、Tabloid）、方向（P 或 L），以及每個 placeholder 的名稱、型別與數值座標，並拒絕重複的 placeholder 名稱。

TemplateDataBinder 會綁定一個資料陣列（以不分大小寫的方式比對至 placeholder 名稱），並依 PlaceholderType 格式化每一個值：

Text / Image / Barcode — 值會以字串原樣傳遞。
Date — 以 placeholder 的格式（預設 Y-m-d）格式化，接受字串、Unix 時間戳記，或 DateTimeInterface。
Number — number_format，小數位數來自格式（預設 2）。
Currency — 以格式字串作為前綴的格式化數字（預設 $）。
Conditional — 依真值性產生 "true" 或 "false"。

結果是一個 BindingResult，承載已綁定的值、缺漏的必填欄位清單，以及任何格式化警告。將已綁定的值轉為一份已彩現的 PDF 是呼叫端的責任，使用 Core document 與 writer API，以及選用的 backgroundPdf 參照。

為何以此方式運作

parser 是唯一具權威性的閘門。它會將不受信任的 JSON 轉為一個不可變、完整具型別的 TemplateDefinition，而綁定接著會作為該值的純函式執行。每一個之後會抵達格式化匯點的欄位，都在解析時被列入允許清單並受長度界限限制。頁面尺寸、方向、數值精度與控制字元全都在此失敗，而非在彩現中途。字串日期會對照一組固定的正規格式進行比對，因此像 now 或 +1 year 這樣的值無法讓輸出取決於掛鐘時間。本模組會刻意停在一個 BindingResult，並將彩現、路徑解析與背景合成留給呼叫端，這使得信任邊界維持明確。

設計背景：Invoices and e-invoicing。

行為合約

**輸入。**一個 JSON 字串（TemplateParser）與一個資料陣列（TemplateDataBinder）。
**輸出。**解析得到 TemplateDefinition；綁定得到 BindingResult。
驗證。validate() 會回傳一個人類可讀錯誤的清單，且絕不拋出；當驗證失敗時，parse() 會拋出 InvalidArgumentException。
**缺漏資料。**一個沒有資料且預設值為空的 placeholder 會被回報於 missingFields 中；一個帶有非空預設值者則使用該預設值。
**決定性。**解析與綁定是其輸入的純函式。

公開 API 介面

型別	種類	主要成員
`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`、coordinates、default、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
}

邊界案例與陷阱

一個無法解析的日期字串會產生一個警告，且原始字串會被保留，而非拋出。
貨幣格式字串會作為一個字面前綴使用（例如 "$" 或 "EUR "），而非一個地區設定識別碼。
backgroundPdf 是承載於定義上的一個路徑參照；本模組不會開啟、驗證或合成它——那是彩現器的工作。
placeholder 名稱以不分大小寫的方式比對；JSON 中重複的名稱是一個驗證錯誤。

效能

解析是一次 JSON 解碼加上結構性驗證；綁定在 placeholder 數量上呈線性。請參閱 performance_budget。

安全注意事項

JSON 會以 JSON_THROW_ON_ERROR 解碼，並在建構一個 TemplateDefinition 之前，對照固定的允許清單進行驗證。本模組不執行任何檔案或網路 I/O；backgroundPdf 路徑不會在此處被解參考，因此路徑處理與存取控制屬於彩現器。

一致性

本模組沒有直接的 PDF 規範範圍：它會解析一份 JSON 範本並格式化值。頁面尺寸與方向詞彙是 NextPDF 慣例，而非規範性的 PDF 構造。

Core 回退/替代方案

沒有 Core 範本定義層。對於完全命令式的文件建構，請直接使用開源的 Core document 與 writer API。請參閱 /modules/core/document/。

Enterprise 邊界註記

本模組定義並綁定範本。它不執行郵件合併協調、批次作業排程或彩現；那些範疇不在本模組範圍內，並在他處處理。

發佈邊界

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