Pro エディション

フォーム

概要

NextPDF Pro は、インタラクティブフォームのデータ（AcroForm のフィールド値、XFDF データファイル、XFA（XML Forms Architecture）テンプレートが保持するデータ）を読み書きします。オープンソースの Core フォームリーダーを、データバインディング、抽出、シリアライズで補完します。

提供状況とライセンス

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

フォームは Pro エディションの一部です。機能ごとの個別ライセンスフラグはありません。

インストール

composer require nextpdf/pro:^3

フォーム機能には、有効な NextPDF Pro ライセンスが必要です。提供状況とライセンスを参照してください。

概念の概要

PDF のインタラクティブフォーム（AcroForm と呼ばれることもあります）は、ISO 32000-2 §12.7 で定義されているとおり、各フィールドをフィールド辞書に格納します。NextPDF Pro は、Core フォームリーダーの上に 3 つの機能を追加します。

AcroForm のラウンドトリップ。 FormDataExtractor は、解析済みのフォームフィールドからフィールド名と値のペアを読み取り、XfdfData オブジェクトまたはプレーンな name → value マップを生成します。XfdfWriter はその逆を行い、XFDF ドキュメントを生成します。
XFDF の読み書き。 XFDF は、ISO 19444-1:2019 が記述するフォーム値の XML データ交換フォーマットです。XfdfParser は XFDF ファイルを構造化データに読み込みます。XfdfWriter は、ソース PDF への任意の参照を伴って、フィールド値を XFDF にシリアライズします。
XFA データの抽出。 XfaParser は、ドキュメント内の XFA パケットを特定し、XML フラグメントを連結し、template パケットと datasets パケットを構造化されたフィールドデータに解析します。

XFA サポートの範囲

NextPDF Pro の XFA サポートは データ指向 であり、完全な XFA レンダリングやスクリプティングのエンジンではありません。パーサーは template パケットと datasets パケットを抽出して構造化し、フィールド定義と値を読めるようにします。XFA のフォーム計算スクリプトを実行したり、動的な XFA レイアウトをレンダリングしたり、すべての XFA パケットタイプをラウンドトリップしたりはしません。特定の XFA フォームセットに依拠する前に、自分のドキュメントに対してパーサーをテストしてください。すべての XML 解析は、外部エンティティの読み込みを無効化します（XXE セーフ）。

この設計の理由

XFA サポートは、意図的にレンダリングではなくデータに範囲を限定しています。ISO 32000-2 は、フォーム辞書の XFA エントリを PDF 2.0 で非推奨としています（§12.7）。完全な XFA レイアウトおよびスクリプティングのエンジンは、ほとんどのワークロードがもはや必要としないレガシーな領域を追いかけることになります。代わりに NextPDF Pro は、耐久性のあるフィールドデータが存在する template パケットと datasets パケットを抽出し、それ以外は扱いません。同じ方針が、XXE を無効化した解析とスキャン上限を導いています。フォーム入力はしばしば信頼できない相手から届くためです。これにより、Pro のフォームサーフェスは、Core の AcroForm モデルの薄く予測可能な拡張として保たれます。

設計の背景: 記入可能なフォームから凍結されたレコードへ: AcroForm の記入とフラット化。

API サーフェス

クラス	責務
`FormDataExtractor`	AcroForm のフィールド値を `XfdfData` または配列として抽出。
`XfdfParser`	XFDF ドキュメントを構造化データに解析。
`XfdfWriter`	フィールド値を XFDF にシリアライズ。任意の PDF 参照を伴う。
`XfaParser`	XFA の template および datasets パケットを抽出して解析。
`FormDataBinder`	データマップをフォームフィールドへバインドし直す。

メソッドレベルの完全なリファレンスは、フォーム詳細リファレンスにあります。

コードサンプル — クイックスタート

use NextPDF\Pro\Form\FormDataExtractor;
use NextPDF\Pro\Form\XfdfWriter;

$values = FormDataExtractor::toArray($fields);
$xfdf   = XfdfWriter::fromFields($fields, 'invoice.pdf');

コードサンプル — 本番

use NextPDF\Pro\Form\XfaParser;
use NextPDF\Pro\Form\Exception\XfaParseException;

try {
    $formData = (new XfaParser())->parse($pdfBytes);
    $logger->info('xfa.parsed', ['fields' => count($formData->fields)]);
} catch (XfaParseException $e) {
    $logger->warning('xfa.parse_failed', ['reason' => $e->getMessage()]);
}

エッジケースと落とし穴

XfaParser は、スキャン上限を超える PDF 入力を、上限なく読み取るのではなく拒否します。
ドキュメントは、インタラクティブフォームと非インタラクティブフォームの両方を保持する場合があります。抽出は終端フィールド辞書を対象とします。
XFDF はフラットなフィールド構造をラウンドトリップします。深くネストされたフィールド階層は、明示的な処理が必要な場合があります。

パフォーマンス

抽出とシリアライズは、フォームフィールドの数に対して線形です。XFA 解析のコストは、埋め込まれた XML パケットのサイズに応じてスケールします。

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

すべての XML 解析は、XXE を防ぐために外部エンティティの解決を無効化します。信頼できないソースからの XFDF と XFA の入力は敵対的なものとして扱い、ドキュメントへバインドし直す前に、解析されたフィールドセットを検証してください。

適合性

振る舞い	参照	ステータス
インタラクティブフォーム/フィールド辞書モデル	ISO 32000-2 §12.7	整合（言い換え）
XFDF データ交換フォーマット	ISO 19444-1:2019	整合

この表は、NextPDF Pro が準拠して構築されている仕様を記録するものです。正式な認証についての言明ではありません。

振る舞いの契約

FormDataExtractor は、解析済みの終端フィールド辞書から名前と値のペアを読み取り、XfdfData オブジェクトまたはプレーンな name → value 配列を返します。
XfdfParser は XFDF ドキュメントを構造化データに解析します。XfdfWriter は、ソース PDF への任意の参照を伴って、フィールド値を XFDF にシリアライズします。
XfaParser は、XFA パケットを特定し、XML フラグメントを連結し、template パケットと datasets パケットを構造化されたフィールドデータに解析します。スキャン上限を超える PDF 入力は、上限なく読み取るのではなく拒否します。
XFA サポートはデータ指向です。パーサーは template パケットと datasets パケットを抽出して構造化します。XFA のフォーム計算スクリプトを実行したり、動的な XFA レイアウトをレンダリングしたり、すべての XFA パケットタイプをラウンドトリップしたりはしません。
すべての XML 解析は、外部エンティティの解決を無効化します（XXE セーフ）。

Enterprise の境界に関する注意

Enterprise はフォームの振る舞いを変更しません。Enterprise は別途文書化された上位ティアのコンプライアンスおよびアーカイブ機能を追加しますが、それらは AcroForm のラウンドトリップ、XFDF の読み書き、XFA データの抽出には必要ありません。

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

NextPDF Core のオープンソースのフォームリーダーは、フォームフィールドを読み取ります。XFDF の読み書き、XFA データの抽出、フィールドのバインディングは Pro の追加機能です。/modules/form/ を参照してください。

公開範囲

このページは、外部から観測可能な振る舞いと、サポートされる公開 API サーフェスのみを記述します。内部の名前空間パス、ヘルパークラス、メカニズムの表、ランブックのファイル名、チケットのプレフィックスは範囲外です。