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）に対してチェックし、向き（P または L）、そして各プレースホルダーの名前、タイプ、数値座標をチェックし、重複するプレースホルダー名を拒否します。

TemplateDataBinder は、データ配列を（プレースホルダー名に対して大文字小文字を区別せずにマッチさせて）バインドし、各値を PlaceholderType ごとにフォーマットします:

Text / Image / Barcode — 値は文字列としてそのまま通過します。
Date — プレースホルダーのフォーマット（デフォルト Y-m-d）でフォーマットされ、文字列、Unix タイムスタンプ、または DateTimeInterface を受け入れます。
Number — フォーマットからの小数桁数（デフォルト 2）を伴う number_format。
Currency — フォーマット文字列を接頭辞（デフォルト $）としてフォーマットされた数値。
Conditional — 真偽値に基づく "true" または "false"。

結果は BindingResult であり、バインドされた値、欠落している必須フィールドのリスト、そして任意のフォーマット警告を保持します。バインドされた値をレンダリング済みの PDF に変換するのは呼び出し元の責務であり、Core のドキュメントおよびライター API と、オプションの backgroundPdf 参照を使用します。

この仕組みが機能する理由

パーサーは唯一の権威あるゲートです。信頼できない JSON を、イミュータブルで完全に型付けされた TemplateDefinition に変換し、その後のバインディングはその値の純粋関数として実行されます。後段のフォーマットシンクに到達するすべてのフィールドは、解析時に許可リスト化され、長さが制限されます。ページサイズ、向き、数値精度、制御文字はすべて、レンダリング途中ではなくここで失敗します。文字列の日付は固定された正規フォーマットの集合に対してマッチされるため、now や +1 year のような値が出力を実時間に依存させることはできません。このモジュールは意図的に BindingResult で止まり、レンダリング、パス解決、背景の合成は呼び出し元に委ねられます。これにより信頼境界が明示的に保たれます。

設計の背景: Invoices and e-invoicing。

振る舞いの契約

Input. JSON 文字列（TemplateParser）とデータ配列（TemplateDataBinder）。
Output. 解析からの TemplateDefinition、バインディングからの BindingResult。
Validation. validate() は人間が読めるエラーのリストを返し、決してスローしません。parse() は検証が失敗したときに InvalidArgumentException をスローします。
Missing data. データがなく、デフォルトが空のプレースホルダーは missingFields に報告されます。空でないデフォルトを持つものはそのデフォルトを使用します。
Determinism. 解析とバインディングは、その入力の純粋関数です。

公開 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`	名前、`PlaceholderType $type`、座標、デフォルト、フォーマット
`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 は定義に保持されるパス参照です。このモジュールはそれを開いたり、検証したり、合成したりしません。それはレンダラーの仕事です。
プレースホルダー名は大文字小文字を区別せずにマッチされます。JSON 内の重複する名前は検証エラーです。

パフォーマンス

解析は 1 回の JSON デコードと構造検証です。バインディングはプレースホルダー数に対して線形です。performance_budget を参照してください。

セキュリティに関する注意

JSON は JSON_THROW_ON_ERROR でデコードされ、TemplateDefinition が構築される前に固定の許可リストに対して検証されます。このモジュールはファイルやネットワークの I/O を一切行いません。backgroundPdf パスはここでは参照解決されないため、パスの取り扱いとアクセス制御はレンダラーに属します。

適合性

このモジュールには直接的な PDF 仕様サーフェスはありません。JSON テンプレートを解析し、値をフォーマットします。ページサイズと向きの語彙は NextPDF の規約であり、規範的な PDF 構成要素ではありません。

Core のフォールバック/代替手段

Core のテンプレート定義レイヤーはありません。完全に命令的なドキュメント構築には、オープンソースの Core ドキュメントおよびライター API を直接使用してください。/modules/core/document/ を参照してください。

Enterprise の境界に関する注記

このモジュールはテンプレートを定義してバインドします。差し込み印刷のオーケストレーション、バッチジョブのスケジューリング、レンダリングは行いません。それらの関心事は対象外であり、他の場所で処理されます。

公開の境界

このページは、外部から観測可能な挙動と、サポートされているパブリック API サーフェスのみを記述しています。内部の名前空間パス、ヘルパークラス、メカニズムのテーブル、ランブックのファイル名、チケットの接頭辞は対象外です。