Interop — 詳細リファレンス

概要

このページは NextPDF\Pro\Interop\V1 のコントラクトレベルのリファレンスです。このモジュールには 14 個の公開シンボルが含まれます：1 つのシリアライズコントラクト（InteropResultInterface）、1 つの CI 整合性ガード（SchemaLock）、3 つのトップレベル結果 DTO（ExtractedText、DocumentSegmentation、FormData）、そして 9 個の補助的な値オブジェクトと列挙型です。すべての DTO は、1 つの解析結果に対する不変で JSON シリアライズ可能なビューです。ワイヤ形状はバージョン管理およびロックされており、このサーフェスでは解析が再実行されることはありません。タスク指向のビューは機能ページにあります。

提供状況とライセンス

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

このモジュールをゲートするランタイム機能フラグはありません。nextpdf/pro がインストールされライセンスされていれば、これらのクラスはいつでも利用可能です。

公開 API サーフェス

シンボル	パラメーター	デフォルト挙動	戻り値	スロー/失敗条件	備考
InteropResultInterface	—	トップレベル結果 DTO 向けのコントラクト。JsonSerializable を拡張	—	スローしない	SCHEMA_VERSION は文字列 '1.0'。
InteropResultInterface::toArray()	なし	常に schema_version を持つ JSON セーフな配列にシリアライズ	array<string, mixed>	スローしない	実装は type 判別子も出力。
InteropResultInterface::toJson()	int $flags = 0	toArray() の出力をエンコード。JSON_THROW_ON_ERROR は常に OR 結合	string	エンコード不可データで JsonException	JSON_PRETTY_PRINT などのフラグを渡す。
SchemaLock::verify()	なし	ディスク上の V1 schema.json をハッシュ化し、ロックされた SHA-256 と比較	bool	スローしない	スキーマファイルが欠落・読み取り不可・変更されている場合は false。
SchemaLock::expectedHash()	なし	ロックされたハッシュを返す	string	スローしない	CI 失敗のトリアージ向け診断出力。
SchemaLock::actualHash()	なし	現在のスキーマファイルのハッシュを返す	string	スローしない	I/O 失敗時はハッシュの代わりにセンチネル文字列 FILE_NOT_FOUND / READ_FAILED。
BoundingBox	float $x、float $y、float $width、float $height	PDF ユーザー空間ポイントでの不変ボックス。原点は左下	—	スローしない	area()、overlaps()、toArray()、fromArray()。
DocumentInfo	int $pageCount と 6 つの任意メタデータフィールド	不変のドキュメントメタデータ	—	スローしない	fromArray() は全フィールドを型ガード。欠落フィールドはデフォルトにフォールバック。
PageInfo	int $pageNumber、float $width、float $height、int $rotation = 0	不変のページメタデータ	—	スローしない	isLandscape()。fromArray() は数値文字列と浮動小数点数を型変換。
ExtractedText	list<ExtractedPage> $pages、DocumentInfo $documentInfo、float $processingTimeMs = 0.0	ドキュメント全体のテキスト抽出結果	—	toJson() からのみ JsonException	page()、totalBlockCount()、plainText()、fromArray()。
ExtractedPage	PageInfo $pageInfo、list<TextBlock> $textBlocks	読み順のテキストブロックを保持するページ単位のコンテナ	—	スローしない	plainText() はブロック内容を単一スペースで連結。
TextBlock	string $content、BoundingBox $boundingBox、int $pageNumber、string $fontName = ''、float $fontSize = 0.0	位置付けされた連続テキストラン	—	スローしない	フォント名とサイズはベストエフォート（ブロック内の支配的フォント）。
DocumentSegmentation	list<Segment> $segments、DocumentInfo $documentInfo、float $processingTimeMs = 0.0	レイアウトを考慮したセグメンテーション結果	—	toJson() からのみ JsonException	segmentCount()、ofType()、onPage()、contentSegments()、fromArray()。
Segment	SegmentType $type、string $content、BoundingBox $boundingBox、int $pageNumber、float $confidence = 1.0、list<Segment> $children = []	分類されたページ領域。子は再帰的にネスト	—	スローしない	isHighConfidence() のしきい値は 0.8。descendantCount() は再帰的。
SegmentType	文字列バック列挙型	heading から unknown までの 12 ケース	—	スローしない	isContent() と isStructural() がケースを分割。
FormData	list<FormField> $fields、DocumentInfo $documentInfo、float $processingTimeMs = 0.0	ドキュメント全体のフォーム抽出結果	—	toJson() からのみ JsonException	field()、dataFields()、filledCount()、toKeyValueMap()、fromArray()。
FormField	string $name、FormFieldType $type、と 6 つの任意フィールド	抽出された単一のフォームフィールド	—	スローしない	isFilled() は value !== ''。
FormFieldType	文字列バック列挙型	text から button までの 8 ケース	—	スローしない	isDataField() は button と signature で false。

interface InteropResultInterface extends JsonSerializable

public const SCHEMA_VERSION = '1.0';

public function toArray(): array;

public function toJson(int $flags = 0): string;

final class SchemaLock

public static function verify(): bool

public static function expectedHash(): string

public static function actualHash(): string

final readonly class ExtractedText implements InteropResultInterface

public function __construct(
    public array $pages,
    public DocumentInfo $documentInfo,
    public float $processingTimeMs = 0.0,
)

public function page(int $pageNumber): ?ExtractedPage

public function totalBlockCount(): int

public function plainText(): string

public static function fromArray(array $data): self

final readonly class DocumentSegmentation implements InteropResultInterface

public function __construct(
    public array $segments,
    public DocumentInfo $documentInfo,
    public float $processingTimeMs = 0.0,
)

public function ofType(SegmentType $type): array

public function onPage(int $pageNumber): array

public function contentSegments(): array

public static function fromArray(array $data): self

final readonly class FormData implements InteropResultInterface

public function __construct(
    public array $fields,
    public DocumentInfo $documentInfo,
    public float $processingTimeMs = 0.0,
)

public function field(string $name): ?FormField

public function dataFields(): array

public function toKeyValueMap(): array

public static function fromArray(array $data): self

挙動コントラクト

• バージョン管理されたエンベロープ。 すべてのトップレベル DTO（ExtractedText、DocumentSegmentation、FormData）は InteropResultInterface を実装します。その toArray() の出力は常に schema_version（'1.0'）と type 判別子（extracted_text、document_segmentation、form_data）を持ちます。
• JSON エンコード。 toJson() は、呼び出し側のフラグに JSON_THROW_ON_ERROR を OR 結合したうえで json_encode に委譲します。jsonSerialize() は toArray() に委譲するため、json_encode($dto) は同じ形状を生成します。
• 決定的なシリアライズ。 キーの順序と形状は DTO によって固定されています。Segment::toArray() は空のとき children キーを省略し、FormField::toArray() は null のとき bounding_box を省略します。コンシューマーは両方のキーを任意として扱う必要があります。
• ラウンドトリップ。 各 DTO は、デコード済み JSON オブジェクトを受け取る静的な fromArray() を公開します。フィールドはこのプロセス間境界で型ガードされ、欠落または型不一致の値は、スローする代わりに文書化されたデフォルトにフォールバックします。
• 列挙型のフォールバック。 認識されない type 文字列は、Segment::fromArray() では SegmentType::Unknown に、FormField::fromArray() では FormFieldType::Text にマッピングされます。
• 座標。 BoundingBox の座標は PDF ユーザー空間単位（ポイント、1/72 インチ）で、原点はページの左下隅にあります。ページ番号は全体を通じて 1 始まりです。
• プレーンテキストの連結。 ExtractedPage::plainText() はブロック内容を単一スペースで連結します。ExtractedText::plainText() はページを空行（"\n\n"）で連結します。
• セグメンテーションクエリ。 ofType()、onPage()、contentSegments() はトップレベルのセグメントのみをフィルタリングし、再インデックスされたリストを返します。contentSegments() は SegmentType::isContent() が true となる型（heading、sub_heading、paragraph、table、list、code）を選択します。
• フォームクエリ。 FormData::dataFields() と toKeyValueMap() は、非データフィールド型（button、signature）を除外します。filledCount() は、値が空でない文字列であるフィールドをカウントします。
• スキーマロック。 SchemaLock::verify() は、パッケージに同梱された V1 schema.json を読み取り、CRLF を LF に正規化し、SHA-256 でハッシュ化して、ロックされた定数と定数時間で比較します。CI はこれを用いてサイレントなスキーマドリフトをブロックします。ロック値は、意図的なバージョン付きスキーマ変更があった場合にのみ変化します。
• バージョニングポリシー。 V1 サーフェスは明示的な公開コントラクトです。追加的な変更はスキーマバージョンを更新し、破壊的な変更には新しいメジャーバージョンが必要です。

エッジケースと障害モード

• このサーフェスで唯一スローするメンバーは toJson() です。配列がエンコード不可能な場合（例：抽出内容に無効な UTF-8 が含まれる場合）に JsonException をスローします。
• SchemaLock::verify() は、スキーマファイルが欠落・読み取り不可・変更されている場合、スローせずに false を返します。ドリフトと I/O 失敗を区別するには、expectedHash() と actualHash() を比較します。
• fromArray() のフォールバックは設計上サイレントです。型不一致の page_number は 1 になり、型不一致の confidence はデフォルトになります。捏造されたデフォルトが許容できない場合は、上流で検証してください。
• 数値文字列の型変換は非対称です。PageInfo::fromArray() は int および float フィールドに数値文字列を受け入れますが、Segment と TextBlock は confidence と font_size に int または float のみを受け入れます。
• BoundingBox::fromArray() は、文書化された配列形状に従い 4 つのキーすべてを要求します。これを埋め込む DTO は、ラッパーキーが欠落している場合にゼロボックス（FormField の場合は null）を代用します。
• ExtractedPage::fromArray() は、キーが欠落または型不一致の場合、595 × 842 ポイントのページ 1 というフォールバックの page_info を代用します。
• FormField::fromArray() は、required と read_only に厳密なブール値のみを受け入れます。真と評価される文字列や整数は false にマッピングされます。
• Segment の子は深さ制限なく再帰します。極端に深いネストは、PHP のメモリおよびスタック制限によってのみ制限されます。
• このモジュールでは、暗号鍵や署名の操作は一切行われません。SchemaLock は SHA-256 をファイル整合性のチェックサムとしてのみ使用するため、FIPS モード固有の挙動はありません。

準拠

Interop V1 は、NextPDF が所有するバージョン管理されたワイヤコントラクトです。外部標準を実装するものではないため、規範的な引用テーブルはありません。BoundingBox のセマンティクスは、生成元の Core サブシステムが使用する PDF ユーザー空間座標モデルと整合します。これは構造的な整合性の記述であり、準拠テストの結果ではありません。NextPDF は認証を保有せず、いかなる認証も付与しません。

開発ノート

• コンシューマーでは schema_version で分岐してください。追加的なキーは互換とみなし、未知のメジャーバージョンは明示的に拒否してください。
• CI で SchemaLock::verify() を実行してください。失敗時には expectedHash() と actualHash() をログに記録し、その場での編集ではなく、意図的なバージョン付きスキーマ変更を要求してください。
• プロセス間のラウンドトリップでは、連想配列でデコードし（json_decode($json, true)）、その結果を対応する fromArray() に渡してください。
• すべての DTO は final かつ readonly です。コンポジションで拡張し、公開フィールドから新しいビューを導出してください。
• toKeyValueMap() は、データを保持するフィールドのみをフラット化します。signature フィールドの存在が重要な場合は、FormData::$fields から直接読み取ってください。
• 再利用は安全です。DTO は可変状態もリソースも保持しないため、キャッシュ、リクエスト間での共有、繰り返しのシリアライズが可能です。

公開範囲

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

関連情報

• Interop — 機能ページ
• MCP — 詳細リファレンス（Pro）
• Extraction — 詳細リファレンス（Pro）
• Form — 詳細リファレンス（Pro）