Pro エディション

Interop

概要

NextPDF Pro は、PDF 分析の出力（ドキュメント情報、ページ、テキストブロック、セグメンテーション、フォームデータ）を、外部システムやツールによる消費に向けて、安定したスキーマロック済みの JSON 形状にシリアライズする、バージョン管理された一連の結果データ転送オブジェクト（DTO）を提供します。

提供状況とライセンス

この機能は NextPDF Pro（nextpdf/pro）で提供され、Pro ティアのライセンスエンベロープで有効化されます。そのエンタイトルメントを持たないデプロイでは、この機能のクラスはロードされません。Interop は Pro エディションの一部であり、機能ごとの個別ライセンスフラグはありません。エディションを比較してライセンスを取得する。

インストール

composer require nextpdf/pro:^3

概念の概要

PDF 処理の出力がプロセスやサービスの境界を越えるとき、受信側には安定したコントラクトが必要です。Interop V1 サーフェスがそれを提供します。

InteropResultInterface — すべての結果 DTO がこれを実装します。各 DTO は、常に schema_version キーを保持する JSON セーフな配列にシリアライズされ、また JSON 文字列にもシリアライズされます。
結果 DTO — DocumentInfo、PageInfo、BoundingBox、ExtractedText / ExtractedPage / TextBlock、DocumentSegmentation / Segment、FormData / FormField。各 DTO は、1 つの分析結果の不変のビューです。
SchemaLock — CI ガードです。凍結されたスキーマの SHA-256 を保持し、対応するバージョンの引き上げなしにスキーマファイルが変更された場合はビルドを失敗させます。これにより、ワイヤーコントラクトが暗黙のうちにドリフトすることを防ぎます。

Interop サーフェスは明示的にバージョン管理されています（SCHEMA_VERSION）。これを公開 API コントラクトとして扱ってください。追加的な変更はスキーマを引き上げ、破壊的変更には新しいメジャーバージョンが必要です。

なぜこの仕組みなのか

シリアライズの形状は、実装の詳細ではなく公開 API コントラクトとして扱われます。すべての DTO は schema_version キーを保持するため、消費側は受け取った形状を推測するのではなく、その形状に基づいて分岐できます。SchemaLock は CI で凍結スキーマの SHA-256 を固定するため、バージョンの引き上げなしにフォーマットがドリフトすることはありません。これこそが、外部システムが JSON に対して安全にビルドできる理由です。コントラクトはバージョンが動くときにのみ動きます。出力は移植可能なまま保たれます。文書化され、バージョン管理された、あなたが所有するデータであり、あなたの足元で変わってしまう形状ではありません。

設計背景：オープンコア、ロックインなし。

API サーフェス

クラス	責務
`InteropResultInterface`	共通のシリアライズコントラクト。
`DocumentInfo`, `PageInfo`, `BoundingBox`	共通のドキュメント/ページ DTO。
`ExtractedText`, `ExtractedPage`, `TextBlock`	テキスト抽出 DTO。
`DocumentSegmentation`, `Segment`	ドキュメントセグメンテーション DTO。
`FormData`, `FormField`	フォームデータ DTO。
`SchemaLock`	CI のスキーマドリフトガード。

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

$json = $result->toJson(JSON_PRETTY_PRINT);
$array = $result->toArray(); // includes 'schema_version'

コードサンプル — 本番

use NextPDF\Pro\Interop\V1\SchemaLock;

if (! SchemaLock::verify()) {
    throw new RuntimeException('Interop schema drift detected — version bump required.');
}
$payload = $result->toArray();
$httpClient->postJson($endpoint, $payload);

エッジケースと落とし穴

toArray() は常に schema_version を含みます。下流の消費側は、これに基づいて分岐すべきです。
SchemaLock::verify() は、スキーマファイルが欠落している、または変更されている場合に false を返します。
DTO は読み取り専用のビューです。分析を再実行することはありません。

パフォーマンス

シリアライズは、結果グラフのサイズに対して線形です。

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

DTO は、あなたが投入した分析出力のみを保持します。シリアライズ中にファイルシステムやネットワークの I/O は発生しません。

適合性

Interop は、NextPDF が所有するバージョン管理されたスキーマを定義します。外部標準を実装するものではありません。

振る舞いの契約

すべての結果 DTO は InteropResultInterface を実装し、常に schema_version キーを保持する JSON セーフな配列にシリアライズされ、また JSON 文字列にもシリアライズされます。
結果 DTO（DocumentInfo、PageInfo、BoundingBox、ExtractedText/ExtractedPage/TextBlock、DocumentSegmentation/Segment、FormData/FormField）は、不変の読み取り専用ビューです。分析を再実行することはありません。
SchemaLock::verify() は、凍結されたスキーマの SHA-256 を保持し、スキーマファイルが欠落している、または変更されている場合に false を返します。これにより、ワイヤーコントラクトが暗黙のうちにドリフトすることを防ぎます。
このサーフェスは明示的にバージョン管理されています（SCHEMA_VERSION）。追加的な変更はスキーマを引き上げ、破壊的変更には新しいメジャーバージョンが必要です。
シリアライズ中にファイルシステムやネットワークの I/O は発生しません。

Enterprise の境界に関する注意

Enterprise は Interop の振る舞いを変更しません。Enterprise は別途文書化された上位ティアの機能を追加しますが、それらはバージョン管理された結果 DTO の使用には必要ありません。

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

スキーマロックされバージョン管理された結果 DTO に相当する Core の機能はありません。これは Pro の追加機能です。

公開範囲の境界

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