Pro Edition

Interop — Ausführliche Referenz

Auf einen Blick

Diese Seite ist die vertragsgenaue Referenz für NextPDF\Pro\Interop\V1. Das Modul enthält vierzehn öffentliche Symbole: einen Serialisierungsvertrag (InteropResultInterface), einen CI-Integritätswächter (SchemaLock), drei Ergebnis-DTOs der obersten Ebene (ExtractedText, DocumentSegmentation, FormData) sowie neun unterstützende Wertobjekte und Enums. Jedes DTO ist eine unveränderliche, JSON-serialisierbare Sicht auf ein Analyseergebnis. Die Wire-Form ist versioniert und gesperrt; nichts auf dieser Oberfläche führt eine Analyse erneut aus. Die aufgabenorientierte Sicht finden Sie auf der Capability-Seite.

Verfügbarkeit & Lizenzierung

Diese Capability ist in NextPDF Pro (nextpdf/pro) enthalten und wird mit einem Lizenz-Envelope der Pro-Stufe aktiviert. Eine Installation ohne diese Berechtigung lädt die Klassen der Capability nicht. Editionen vergleichen und Lizenz erwerben.

Kein Runtime-Capability-Flag steuert den Zugriff auf dieses Modul. Die Klassen sind verfügbar, sobald nextpdf/pro installiert und lizenziert ist.

Öffentliche API-Oberfläche

Symbol	Parameter	Standardverhalten	Rückgabe	Wirft oder scheitert mit	Hinweise
`InteropResultInterface`	—	Vertrag für Ergebnis-DTOs der obersten Ebene; erweitert `JsonSerializable`	—	Wirft nicht	`SCHEMA_VERSION` ist der String `'1.0'`.
`InteropResultInterface::toArray()`	keine	Serialisiert zu einem JSON-sicheren Array, das stets `schema_version` mitführt	`array<string, mixed>`	Wirft nicht	Implementierungen geben außerdem einen `type`-Diskriminator aus.
`InteropResultInterface::toJson()`	`int $flags = 0`	Kodiert die Ausgabe von `toArray()`; `JSON_THROW_ON_ERROR` wird stets per OR hinzugefügt	`string`	`JsonException` bei nicht kodierbaren Daten	Übergeben Sie Flags wie `JSON_PRETTY_PRINT`.
`SchemaLock::verify()`	keine	Hasht die auf der Festplatte liegende V1-`schema.json` und vergleicht sie mit dem gesperrten SHA-256-Wert	`bool`	Wirft nicht	`false`, wenn die Schemadatei fehlt, nicht lesbar oder verändert ist.
`SchemaLock::expectedHash()`	keine	Gibt den gesperrten Hash zurück	`string`	Wirft nicht	Diagnoseausgabe für die CI-Fehlertriage.
`SchemaLock::actualHash()`	keine	Gibt den Hash der aktuellen Schemadatei zurück	`string`	Wirft nicht	Die Sentinel-Strings `FILE_NOT_FOUND` / `READ_FAILED` ersetzen den Hash bei einem E/A-Fehler.
`BoundingBox`	`float $x`, `float $y`, `float $width`, `float $height`	Unveränderliches Rechteck in PDF-User-Space-Punkten, Ursprung unten links	—	Wirft nicht	`area()`, `overlaps()`, `toArray()`, `fromArray()`.
`DocumentInfo`	`int $pageCount` plus sechs optionale Metadatenfelder	Unveränderliche Dokument-Metadaten	—	Wirft nicht	`fromArray()` prüft den Typ jedes Feldes; fehlende Felder greifen auf Standardwerte zurück.
`PageInfo`	`int $pageNumber`, `float $width`, `float $height`, `int $rotation = 0`	Unveränderliche Seiten-Metadaten	—	Wirft nicht	`isLandscape()`; `fromArray()` konvertiert numerische Strings und Floats.
`ExtractedText`	`list<ExtractedPage> $pages`, `DocumentInfo $documentInfo`, `float $processingTimeMs = 0.0`	Ergebnis der Textextraktion für das gesamte Dokument	—	`JsonException` nur aus `toJson()`	`page()`, `totalBlockCount()`, `plainText()`, `fromArray()`.
`ExtractedPage`	`PageInfo $pageInfo`, `list<TextBlock> $textBlocks`	Container von Textblöcken je Seite in Lesereihenfolge	—	Wirft nicht	`plainText()` verbindet Blockinhalte mit einzelnen Leerzeichen.
`TextBlock`	`string $content`, `BoundingBox $boundingBox`, `int $pageNumber`, `string $fontName = ''`, `float $fontSize = 0.0`	Positionierter zusammenhängender Textlauf	—	Wirft nicht	Schriftname und -größe sind Best-Effort (dominante Schrift im Block).
`DocumentSegmentation`	`list<Segment> $segments`, `DocumentInfo $documentInfo`, `float $processingTimeMs = 0.0`	Layoutbewusstes Segmentierungsergebnis	—	`JsonException` nur aus `toJson()`	`segmentCount()`, `ofType()`, `onPage()`, `contentSegments()`, `fromArray()`.
`Segment`	`SegmentType $type`, `string $content`, `BoundingBox $boundingBox`, `int $pageNumber`, `float $confidence = 1.0`, `list<Segment> $children = []`	Klassifizierte Seitenregion; Kinder verschachteln sich rekursiv	—	Wirft nicht	Der Schwellenwert von `isHighConfidence()` ist 0.8; `descendantCount()` ist rekursiv.
`SegmentType`	String-basiertes Enum	Zwölf Fälle, `heading` bis `unknown`	—	Wirft nicht	`isContent()` und `isStructural()` partitionieren die Fälle.
`FormData`	`list<FormField> $fields`, `DocumentInfo $documentInfo`, `float $processingTimeMs = 0.0`	Ergebnis der Formularextraktion für das gesamte Dokument	—	`JsonException` nur aus `toJson()`	`field()`, `dataFields()`, `filledCount()`, `toKeyValueMap()`, `fromArray()`.
`FormField`	`string $name`, `FormFieldType $type`, plus sechs optionale Felder	Einzelnes extrahiertes Formularfeld	—	Wirft nicht	`isFilled()` ist `value !== ''`.
`FormFieldType`	String-basiertes Enum	Acht Fälle, `text` bis `button`	—	Wirft nicht	`isDataField()` ist `false` für `button` und `signature`.

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

Verhaltensvertrag

Versionierter Envelope. Jedes DTO der obersten Ebene (ExtractedText, DocumentSegmentation, FormData) implementiert InteropResultInterface. Seine toArray()-Ausgabe führt stets schema_version ('1.0') und einen type-Diskriminator mit: extracted_text, document_segmentation oder form_data.
JSON-Kodierung. toJson() delegiert an json_encode mit JSON_THROW_ON_ERROR, das per OR zu den Flags des Aufrufers hinzugefügt wird. jsonSerialize() delegiert an toArray(), sodass json_encode($dto) dieselbe Form erzeugt.
Deterministische Serialisierung. Schlüsselreihenfolge und Form sind durch das DTO festgelegt. Segment::toArray() lässt den Schlüssel children weg, wenn er leer ist; FormField::toArray() lässt bounding_box weg, wenn er null ist. Konsumenten müssen beide Schlüssel als optional behandeln.
Round-Trip. Jedes DTO stellt ein statisches fromArray() bereit, das ein dekodiertes JSON-Objekt annimmt. Felder werden an dieser prozessübergreifenden Grenze typgeprüft: fehlende oder falsch typisierte Werte greifen auf dokumentierte Standardwerte zurück, anstatt zu werfen.
Enum-Fallbacks. Ein nicht erkannter type-String wird in Segment::fromArray() auf SegmentType::Unknown und in FormField::fromArray() auf FormFieldType::Text abgebildet.
Koordinaten. BoundingBox-Koordinaten sind PDF-User-Space-Einheiten (Punkte, 1/72 Zoll) mit dem Ursprung in der unteren linken Ecke der Seite. Seitenzahlen sind durchgängig einsbasiert.
Klartext-Verbindungen. ExtractedPage::plainText() verbindet Blockinhalte mit einzelnen Leerzeichen. ExtractedText::plainText() verbindet Seiten mit Leerzeilen ("\n\n").
Segmentierungsabfragen. ofType(), onPage() und contentSegments() filtern nur Segmente der obersten Ebene und geben neu indizierte Listen zurück. contentSegments() wählt die Typen aus, bei denen SegmentType::isContent() true ist: heading, sub_heading, paragraph, table, list, code.
Formularabfragen. FormData::dataFields() und toKeyValueMap() schließen Nicht-Datenfeldtypen (button, signature) aus. filledCount() zählt Felder, deren Wert ein nicht-leerer String ist.
Schema-Lock. SchemaLock::verify() liest die mit dem Paket ausgelieferte V1-schema.json, normalisiert CRLF zu LF, hasht mit SHA-256 und vergleicht in konstanter Zeit mit der gesperrten Konstante. CI verwendet es, um stille Schema-Drift zu blockieren; der Lock-Wert ändert sich nur bei einer bewussten, versionierten Schemaänderung.
Versionierungsrichtlinie. Die V1-Oberfläche ist ein expliziter öffentlicher Vertrag. Additive Änderungen erhöhen die Schemaversion; brechende Änderungen erfordern eine neue Hauptversion.

Grenzfälle & Fehlermodi

Das einzige werfende Mitglied auf dieser Oberfläche ist toJson(): JsonException, wenn das Array nicht kodierbar ist, zum Beispiel bei ungültigem UTF-8 in extrahierten Inhalten.
SchemaLock::verify() gibt false zurück — wirft nie —, wenn die Schemadatei fehlt, nicht lesbar oder verändert ist. Vergleichen Sie expectedHash() mit actualHash(), um Drift von einem E/A-Fehler zu unterscheiden.
fromArray()-Fallbacks sind bewusst stumm. Ein falsch typisiertes page_number wird zu 1; ein falsch typisiertes confidence wird zum Standardwert. Validieren Sie vorgelagert, wenn fabrizierte Standardwerte nicht akzeptabel sind.
Die Konvertierung numerischer Strings ist asymmetrisch. PageInfo::fromArray() akzeptiert numerische Strings für seine int- und float-Felder; Segment und TextBlock akzeptieren für confidence und font_size nur int oder float.
BoundingBox::fromArray() erfordert alle vier Schlüssel gemäß seiner dokumentierten Array-Form. Die DTOs, die es einbetten, setzen ein Nullrechteck (oder null bei FormField) ein, wenn der Wrapper-Schlüssel fehlt.
ExtractedPage::fromArray() setzt ein Fallback-page_info von Seite 1 bei 595 × 842 Punkten ein, wenn der Schlüssel fehlt oder falsch typisiert ist.
FormField::fromArray() akzeptiert für required und read_only nur strikte Booleans; wahrheitswertige Strings und Integer werden auf false abgebildet.
Segment-Kinder rekursieren ohne Tiefenbegrenzung. Extrem tiefe Verschachtelung ist nur durch PHPs Speicher- und Stack-Grenzen beschränkt.
In diesem Modul findet keine kryptografische Schlüssel- oder Signaturoperation statt. SchemaLock verwendet SHA-256 ausschließlich als Datei-Integritätsprüfsumme, sodass es kein FIPS-Modus-spezifisches Verhalten gibt.

Konformität

Interop V1 ist ein NextPDF-eigener, versionierter Wire-Vertrag. Es implementiert keinen externen Standard, daher gibt es keine normative Zitationstabelle. Die BoundingBox-Semantik stimmt mit dem PDF-User-Space-Koordinatenmodell überein, das die erzeugenden Core-Subsysteme verwenden; das ist eine Aussage zur strukturellen Übereinstimmung, kein Konformitätstestergebnis. NextPDF hält keine Zertifizierung und erteilt keine.

Entwicklungshinweise

Verzweigen Sie in Konsumenten anhand von schema_version. Behandeln Sie additive Schlüssel als kompatibel; weisen Sie unbekannte Hauptversionen ausdrücklich zurück.
Führen Sie SchemaLock::verify() in der CI aus. Protokollieren Sie bei einem Fehlschlag expectedHash() und actualHash() und verlangen Sie eine bewusste, versionierte Schemaänderung, niemals eine In-Place-Bearbeitung.
Verwenden Sie für prozessübergreifende Round-Trips assoziative Arrays beim Dekodieren (json_decode($json, true)) und übergeben Sie das Ergebnis an das passende fromArray().
Alle DTOs sind final und readonly. Erweitern Sie über Komposition; leiten Sie neue Sichten aus den öffentlichen Feldern ab.
toKeyValueMap() flacht nur datentragende Felder ab. Lesen Sie signature-Felder direkt aus FormData::$fields, wenn ihr Vorhandensein von Bedeutung ist.
Wiederverwendung ist sicher: Die DTOs halten keinen veränderlichen Zustand und keine Ressourcen, sodass sie zwischengespeichert, über Anfragen hinweg geteilt und wiederholt serialisiert werden können.

Publikationsgrenze

Diese Seite dokumentiert ausschließlich extern beobachtbares Verhalten und die unterstützte öffentliche API-Oberfläche. Interne Namespace-Pfade, Hilfsklassen, Mechanismus-Tabellen, Runbook-Dateinamen und Ticket-Präfixe liegen außerhalb des Umfangs.