コンテンツにスキップ
NextPDF
getnextpdf.com

Pro エディション

Form — 詳細リファレンス

概要

「概要」という見出しのセクション

このページは、Pro Form モジュールの詳細リファレンスです。AcroForm 値の抽出、XFDF の読み書き、データバインディング、XFA データ抽出を扱います。本モジュールは、Core フォームリーダーが生成する NextPDF\Form\FormField 値を受け取り、その上にシリアライズ、パース、バインディングを追加します。XFA のサポートはデータ指向です：パーサーは template パケットと datasets パケットを構造化します。XFA の計算スクリプトの実行や、動的な XFA レイアウトのレンダリングは行いません。

提供とライセンス

「提供とライセンス」という見出しのセクション

この機能は NextPDF Pro（nextpdf/pro）で提供され、Pro ティアのライセンスエンベロープで有効化されます。そのエンタイトルメントがないデプロイメントでは、この機能のクラスはロードされません。エディションを比較してライセンスを取得。

機能ごとのライセンスフラグはありません。これは Pro エディションの機能です。

パブリック API サーフェス

「パブリック API サーフェス」という見出しのセクション
記号パラメータデフォルト挙動戻り値スロー/失敗条件備考
FormDataExtractor::extractlist<FormField> $fields各フィールドの名前と値を読み取りXfdfData—値が空のフィールドも含む。
FormDataExtractor::toArraylist<FormField> $fieldsname → value の文字列マップを構築array<string, string>—後方の重複した名前が前方を上書き。
FormDataExtractor::toXfdflist<FormField> $fields, ?string $pdfHref = nullXfdfWriter::fromFields に委譲string（XFDF XML）—ワンコールでエクスポートする簡便パス。
FormDataExtractor::extractNonEmptylist<FormField> $fields値が空文字列のフィールドをスキップXfdfData——
FormDataExtractor::getEmptyFieldNameslist<FormField> $fields値が設定されていないフィールドの名前を列挙list<string>—extractNonEmpty の補集合。
XfdfWriter::fromFieldslist<FormField> $fields, ?string $pdfHref = nullname → value のペアを収集し、fromArray に委譲string（XFDF XML）——
XfdfWriter::fromArrayarray<string, string> $data, ?string $pdfHref = nullマップを XfdfData にラップし委譲string（XFDF XML）——
XfdfWriter::fromXfdfDataXfdfData $data, ?string $pdfHref = nullXFDF にシリアライズ。ドット記法の名前は階層的な <field> 要素としてネストstring（XFDF XML）—XML 1.0 で不正な制御文字を除去。挙動コントラクトを参照。
XfdfParser::parsestring $xfdfXmlXML を XXE セーフに読み込み、フィールドをドット記法へフラット化XfdfDataInvalidArgumentException入力上限は 10 MiB。名前空間付き/なしのルートを受け付け。
XfdfParser::parseFilestring $filePathパスを解決し、ファイルを読み込み、parse に委譲XfdfDataInvalidArgumentException存在しない・ファイルでない・読み取れないパスは例外。
XfaParser::parsestring $pdfDataマーカー確認、XML 抽出、パケット解析XfaFormDataInvalidArgumentException, XfaParseException/XFA マーカーがない場合はエラーではなく空の結果を返す。
XfaParser::hasXfastring $pdfDataバイト列から /XFA マーカーをスキャンbool—バイトマーカースキャン。トークンが出現すればマッチ。
XfaParser::extractXfaXmlstring $pdfDataXFA マーカーをストリームスキャンし、続いて <xdp:xdp> を直接検索string（XFA XML または ''）RuntimeException（宣言）入力の先頭 50 MiB までをスキャン。
XfaParser::parseXmlstring $xmltemplate パケットと datasets パケットを抽出し、<field> 要素を解析XfaFormDataXfaParseExceptionXML 上限は 10 MiB。DOM 読み込み前に強制。
FormDataBinder::bindlist<FormField> $fields, XfdfData $dataバインドされた値を持つ新しい FormField インスタンスを生成FormDataBindResult—元のオブジェクトは変更されない。チェックボックスは Yes/Off に正規化。
FormDataBinder::fromXfdflist<FormField> $fields, string $xfdfXmlXFDF を解析してからバインドFormDataBindResultInvalidArgumentException失敗モードは XfdfParser::parse と同じ。
FormDataBinder::fromArraylist<FormField> $fields, array<string, string> $dataマップを XfdfData にラップしてからバインドFormDataBindResult——
FormDataBindResultisFullyBound, hasNoUnmatchedKeys, boundCount, fieldCount; readonly fields, boundFieldNames, unmatchedDataKeys, unboundFieldNamesイミュータブルなバインド診断メソッドごと—isFullyBound は未マッチキー 0 かつ未バインドフィールド 0 を要求。
XfdfDatahasField, getValue, count, isEmpty, getFieldNames, withField, withoutField, merge; readonly fieldsイミュータブルな name → value コンテナメソッドごと—with* と merge は新しいインスタンスを返す。merge は引数側の値を優先。
XfaFormDatagetField, hasField, count, fieldNames; readonly fields, templateXml, datasetsXmlイミュータブルな XFA 解析結果メソッドごと—ラウンドトリップ用に生の template パケットと datasets パケットの XML を保持。
XfaFormFieldreadonly name, type, value, required, caption, optionsイミュータブルな単一フィールドレコード——type は text, numeric, date, choice, button, signature のいずれか。
XfaPacketenum ケース Template, Datasets, Config, LocaleSet, ConnectionSet, Form; xmlNamespace()文字列バック型のパケット列挙xmlNamespace() からの string—名前空間 URI は XFA Specification 3.3 に従う。
public static function extract(array $fields): XfdfData
public static function toArray(array $fields): array
public static function toXfdf(array $fields, ?string $pdfHref = null): string
public static function extractNonEmpty(array $fields): XfdfData
public static function getEmptyFieldNames(array $fields): array
public static function fromFields(array $fields, ?string $pdfHref = null): string
public static function fromArray(array $data, ?string $pdfHref = null): string
public static function fromXfdfData(XfdfData $data, ?string $pdfHref = null): string
public static function parse(string $xfdfXml): XfdfData
public static function parseFile(string $filePath): XfdfData
public function parse(string $pdfData): XfaFormData
public function hasXfa(string $pdfData): bool
public function extractXfaXml(string $pdfData): string
public function parseXml(string $xml): XfaFormData
public static function bind(array $fields, XfdfData $data): FormDataBindResult
public static function fromXfdf(array $fields, string $xfdfXml): FormDataBindResult
public static function fromArray(array $fields, array $data): FormDataBindResult

例外

「例外」という見出しのセクション
  • NextPDF\Pro\Form\Exception\XfaParseException は RuntimeException を継承 — XFA ペイロードを XfaFormData に解析できない場合。このサブクラス化は意図的です：既存の catch (RuntimeException $e) を使う呼び出し箇所がそのまま動作し続けます。
  • SPL InvalidArgumentException — XfdfParser への空・過大・不正・非 XFDF の入力、XfaParser::parse への空の PDF 入力、XfdfParser::parseFile での読み取り不可なパス。

挙動コントラクト

「挙動コントラクト」という見出しのセクション

AcroForm 抽出。 FormDataExtractor は、渡されたフィールドリストを走査し、各フィールドの名前と値を読み取ります。extract は XfdfData を返し、toArray はプレーンな name → value の文字列マップを返します。extractNonEmpty は値が空文字列のフィールドを除外し、getEmptyFieldNames はその補集合の名前リストを返します。抽出が入力フィールドを変更することはありません。

XFDF 書き込み。 XfdfWriter は、ISO 19444-1:2019 の構造に準拠するドキュメントを生成します。出力は XFDF XML 宣言と、Adobe の XFDF 名前空間（http://ns.adobe.com/xfdf/）にある xfdf ルート（xml:space="preserve" 付き）で始まります。pdfHref が非 null の場合、ソース PDF を指す <f href="..."/> 参照を出力します。ドット記法のフィールド名（例：address.city）は、階層的な <field> 要素ツリーへネストします。値と属性は、5 つの XML メタ文字をエスケープします。フィールド名、値、pdfHref は、整形式性のためにさらに正規化されます：XML 1.0 が禁止する C0 制御文字は除去され、TAB、LF、CR は保持されます。この正規化は設計上ロッシーであり、呼び出し側が渡したバイトに関わらず、ライターは常に整形式で再パース可能な XFDF を出力します。

XFDF 読み込み。 XfdfParser は、名前空間付き・なしの両方の xfdf ルートを受け付け、ルート名を大文字小文字を区別せずにマッチします。一部のプロデューサーが大文字のルート要素を出力するためです。階層的な <field> ツリーはドット記法の名前へ戻され、書き込みと読み込みがラウンドトリップします。すべての XML 読み込みは、ネットワークアクセスと外部エンティティ解決を無効化します。parseFile は、同じパースの前にパス解決と読み取り可能性チェックを追加します。

データバインディング。 FormDataBinder::bind は、データキーをフィールド名に対してマッチします。FormField はイミュータブルなため、バインディングは更新された値を持つ新しいインスタンスを生成し、元のオブジェクトは変更されません。結果は 3 つの診断セットを報告します：バインドされたフィールド名、マッチするフィールドがないデータキー、データを受け取らなかったフィールド。チェックボックスの値は、ISO 32000-2:2020, 12.7.5.2.3 のオン/オフ状態モデルに正規化されます：大文字小文字を区別しない yes、true、1、on は Yes にマッピングされ、その他のすべての値は Off にマッピングされます。

XFA データ抽出。 XfaParser::parse は生の PDF バイト列を受け取ります。まず /XFA マーカーをスキャンし、マーカーがなければ空の XfaFormData を返します。続いて抽出は 2 つの戦略を試みます：XFA XML インジケーターを求めて stream…endstream ブロックをスキャンし、次に <xdp:xdp> ドキュメントを直接検索します。単一の xdp:xdp フラグメントはそのまま返され、複数のフラグメントは合成された xdp:xdp エンベロープに連結されます。parseXml は template パケットと datasets パケットを抽出し、各 template の <field> 要素を XfaFormField へ解析します：name 属性は必須、type はフィールドの UI 子要素から導出、required フラグは nullTest が error に設定された validate 要素から導出、choice の選択肢は items 子要素から取得されます。

XFA のサポートはデータ指向です。パーサーは template パケットと datasets パケットを構造化します。XFA の計算スクリプトの実行、動的な XFA レイアウトのレンダリング、すべてのパケットタイプのラウンドトリップは行いません。これに依存する前に、対象とする特定のドキュメントセットに対してパーサーを検証してください。

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

「エッジケースと失敗モード」という見出しのセクション
  • XfdfParser::parse('') は InvalidArgumentException をスローします。10 MiB を超える入力は、上限を明示する InvalidArgumentException をスローします。
  • 不正な XML は、収集された libxml メッセージを含む InvalidArgumentException をスローします。ルートが xfdf でない整形式ドキュメントは、実際のルート要素を明示してスローします。
  • <fields> 要素を持たない XFDF ドキュメントは、空の XfdfData に解析されます。これはエラーではありません。
  • name 属性を持たないフィールド要素は、XFDF と XFA の両方の解析でスキップされます。<value> 子要素を持たない XFDF フィールドは、エントリを生成しません。
  • XfaParser::parse('') は InvalidArgumentException をスローします。/XFA マーカーを持たない PDF、または XFA XML を特定できない PDF は、スローするのではなく空の XfaFormData を返します。
  • hasXfa はバイトマーカースキャンです：未使用オブジェクト内のものも含め、ファイル内の任意の /XFA トークンがマッチします。使用可能な XML が存在するかどうかは、後続の抽出ステップが判断します。
  • XFA 抽出は、PDF バイト列の先頭 50 MiB までを検査します。その境界を超えるコンテンツはスキャンされません。
  • 10 MiB を超える XFA XML は、DOM ツリーが具現化される前に XfaParseException をスローします。不正な XFA XML は、libxml メッセージを含む XfaParseException をスローします。
  • チェックボックスの正規化は、認識されない値をそのまま通すことはありません。受け付けられるオン形式以外はすべて Off にマッピングされます。
  • ライターの制御文字除去はロッシーです：名前、値、または pdfHref 内の XML 1.0 で不正な C0 バイトは、出力が整形式のままとなるよう除去されます。TAB、LF、CR は残ります。
  • すべての XML 解析は、外部エンティティ解決とネットワークアクセスを無効化します（XXE セーフ）。
  • 本モジュールは暗号操作を一切実行しません。FIPS モードでも挙動は変わりません。

適合性

「適合性」という見出しのセクション
挙動参照ステータス
インタラクティブフォーム/フィールドディクショナリモデルISO 32000-2:2020, 12.7準拠（製品ベース）
チェックボックスのオン/オフ状態正規化（Yes/Off）ISO 32000-2:2020, 12.7.5.2.3準拠。本ページの引用記録で条項を引用
XFDF データ交換構造ISO 19444-1:2019準拠（製品ベース）
XFA パケット名と名前空間 URIXFA Specification 3.3準拠（製品ベース）

オーサリング時点で利用可能な RAG コーパスには、ISO 19444-1:2019、XFA Specification、W3C XML 1.0 が含まれていないため、これらの整合性の記述は、条項引用ではなく、ソース注釈とテストに基づく製品ベースのものです。これらの記述は、参照ドキュメントに対する能力を説明するものです。NextPDF は適合性認証を保有しておらず、ある条項へのサポートは認証の表明ではありません。

開発上の注意

「開発上の注意」という見出しのセクション
  • XfaParser を除くすべてのエントリポイントは静的です。XfaParser はインスタンス化可能でステートレスであり、1 つのインスタンスを複数のドキュメントで再利用しても安全です。
  • 意図されたラウンドトリップは次のとおりです：Core フォームリーダーが FormField 値を生成し、FormDataExtractor または XfdfWriter がそれをシリアライズし、XfdfParser がデータを読み戻し、FormDataBinder がそれをフィールドリストに適用します。階層的な名前は、ドット記法を通じてラウンドトリップを生き延びます。
  • FormDataBindResult の診断（isFullyBound、unmatchedDataKeys、unboundFieldNames）を使って、フィルを受け入れる前に、XFDF データファイルと改訂された PDF テンプレートの間のドリフトを検出してください。
  • XfdfData は値オブジェクトです：withField、withoutField、merge は新しいインスタンスを返します。キーの衝突時には、merge は引数側の値を優先します。
  • XfaFormData は、生の template パケットと datasets パケットの XML（templateXml、datasetsXml）を保持するため、フィールドモデルがカバーしないパケットを後処理できます。
  • 本モジュールは、PDF バイト列から AcroForm ディクショナリを自ら解析することはありません。Core フォームリーダーが生成するフィールドを受け取ります。生の PDF コンテンツを操作するのは XfaParser のみです。

公開範囲

「公開範囲」という見出しのセクション

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

関連項目

「関連項目」という見出しのセクション