Template — 詳細リファレンス

概要

この詳細リファレンスでは、受け入れられる JSON テンプレートスキーマ、すべての検証ルール、そしてデータバインダーのタイプごとの正確なフォーマット挙動について説明します。本モジュールはテンプレート定義を解析し、呼び出し側のデータを型付きプレースホルダーにバインドします。フォーマット済みの文字列を出力しますが、PDF オブジェクトの描画は行いません。

提供状況とライセンス

この機能は NextPDF Pro（nextpdf/pro）で提供され、Pro ティアのライセンスエンベロープで有効化されます。その資格を持たないデプロイメントは、この機能のクラスを読み込みません。このモジュールをゲートするランタイムのケーパビリティフラグはありません。エディションを比較してライセンスを取得。

公開 API サーフェス

本モジュールは 2 つのエントリーポイントサービスと 4 つの不変値オブジェクトを公開します。以下のすべてのシンボルは公開かつ安定しています。

シンボル	パラメーター	既定の挙動	戻り値	スローまたは失敗内容	備考
TemplateParser::parse	string $json	検証してから定義を構築	TemplateDefinition	検証エラーがある場合は InvalidArgumentException	まず validate に委譲。
TemplateParser::validate	string $json	すべての構造エラーを 1 パスで収集	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 = ''	1 つのプレースホルダー領域を格納	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 が空のとき true。
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 で true。

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 が 1 つの例外に集約します）:

• name が欠落または空。
• pageSize が許可リスト外、または orientation が P でも L でもない。
• placeholders の欠落、または配列でない値。
• プレースホルダーごと: 名前の欠落または空、不正なタイプ、x、y、width、height の欠落または非数値、名前の重複（大文字小文字を区別しない）。
• defaultValue: 文字列でない、4096 バイトを超える、または ASCII 制御文字を含む。
• format: 文字列でない、256 バイトを超える、または ASCII 制御文字を含む。
• 非負整数でない、または 30 を超える number プレースホルダーの format。

バインディングセマンティクス（TemplateDataBinder::bind）:

• データキーは、プレースホルダー名との大文字小文字を区別しないマッチングのために小文字化されます。
• 空でない既定値を持つ欠落キーは既定値をバインドし、既定値を持たない欠落キーは missingFields に報告されます。
• テキスト、画像、バーコードの値は、変更されずに文字列へキャストされます。
• 日付バインディングは、DateTimeInterface、整数の Unix タイムスタンプ、または 4 つの明示的フォーマットのいずれかの文字列を受け入れます。既定の出力フォーマットは Y-m-d です。
• 数値バインディングは number_format(value, decimals, '.', ',') を使用します。小数桁数は format に由来し、既定値は 2、範囲は 0 から 30 に制限されます。
• 通貨バインディングは、フォーマット済みの数値の前に format を付与し、接頭辞の既定値は $ です。
• 条件バインディングは、真偽値キャストから "true" または "false" を出力します。

エッジケースと失敗モード

• backgroundPdf が本モジュールによって開かれたり参照解決されたりすることはありません。レンダラーに渡される不透明な文字列です。
• Number または Currency プレースホルダーにバインドされた非数値の値は警告を生成します。値は拒否されず、文字列へキャストされます。
• 日付文字列は厳密に解析されます。相対的または自然言語のトークン（「now」、「+1 year」、「tomorrow」）は、受け入れられるフォーマットに一致しないため、警告を出し、生の値がそのまま通過します。
• 整数の日付値は、@ エポック形式を介して Unix タイムスタンプとして読み取られます。
• バインダーに到達した 0 から 30 の範囲外の Number format 精度は警告とともに拒否され、バインダーは既定の精度 2 にフォールバックします。
• 本モジュールでは暗号操作が一切発生しないため、FIPS モード固有の挙動はありません。

適合性

直接的な PDF 仕様サーフェスはありません。ページサイズと向きの語彙は NextPDF の規約であり、本モジュールは PDF オブジェクトではなくフォーマット済みの値を出力します。厳密な文字列日付の許可リストは、RFC 3339 §5.6 で定義される ISO 8601 のインターネット日時プロファイルを、Y-m-d の暦日付および 2 つのローカル日時形式とともに受け入れます。NextPDF はこれらのフォーマットを読み取る機能を文書化していますが、RFC 3339 または ISO 8601 に対する認証は主張しません。

開発上の注意

• TemplateParser と TemplateDataBinder はステートレスです。単一のインスタンスは再利用可能で、バインディング間で共有しても安全です。
• 4 つの値オブジェクトは final readonly です。本番入力については、手動ではなくパーサーを介して構築してください。
• validate はすべての構造エラーを 1 パスで報告し、parse はまず validate を呼び出して集約されたメッセージでスローします。フォーム形式のフィードバックには validate を、フェイルファストな取り込みには parse を使用してください。
• 長さと精度の境界は、権威あるゲートとしてパーサーで強制されます。TemplateDataBinder は、number_format のメモリ増幅に対するシンク側のガードとして、数値精度を再チェックします。

公開の境界

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

関連項目

• Template（機能ガイド）
• Toc
• Merge