Interop

Auf einen Blick

NextPDF Pro stellt einen versionierten Satz von Ergebnis-Datentransferobjekten (DTOs) bereit, die PDF-Analyseausgaben — Dokumentinfo, Seiten, Textblöcke, Segmentierung und Formulardaten — in eine stabile, schema-gesperrte JSON-Form serialisieren, zur Verwendung durch externe Systeme und Werkzeuge.

Verfügbarkeit & Lizenzierung

Diese Fähigkeit wird in NextPDF Pro (nextpdf/pro) ausgeliefert und aktiviert sich mit einer Lizenzhülle der Pro-Stufe. Eine Bereitstellung ohne diese Berechtigung lädt die Klassen der Fähigkeit nicht. Interop ist Teil der Pro-Edition; es gibt kein separates Lizenz-Flag pro Funktion. Editionen vergleichen und Lizenz erwerben.

Installation

composer require nextpdf/pro:^3

Konzeptioneller Überblick

Wenn die PDF-Verarbeitungsausgabe eine Prozess- oder Dienstgrenze überquert, benötigt der Empfänger einen stabilen Vertrag. Die Interop-V1-Oberfläche stellt diesen bereit:

• InteropResultInterface — jedes Ergebnis-DTO implementiert dieses. Jedes serialisiert zu einem JSON-sicheren Array, das stets einen schema_version-Schlüssel trägt, sowie zu einem JSON-String.
• Ergebnis-DTOs — DocumentInfo, PageInfo, BoundingBox, ExtractedText / ExtractedPage / TextBlock, DocumentSegmentation / Segment und FormData / FormField. Jedes ist eine unveränderliche Sicht auf ein Analyseergebnis.
• SchemaLock — eine CI-Absicherung. Sie hält den SHA-256 des eingefrorenen Schemas und lässt den Build fehlschlagen, wenn sich die Schema-Datei ohne entsprechende Versionserhöhung ändert, sodass der Wire-Vertrag nicht stillschweigend abdriften kann.

Die Interop-Oberfläche ist explizit versioniert (SCHEMA_VERSION). Behandeln Sie sie als öffentlichen API-Vertrag: additive Änderungen erhöhen das Schema; brechende Änderungen erfordern eine neue Major-Version.

Warum es so funktioniert

Die Serialisierungsform wird als öffentlicher API-Vertrag behandelt, nicht als Implementierungsdetail. Jedes DTO trägt einen schema_version-Schlüssel, sodass Konsumenten anhand der empfangenen Form verzweigen, statt zu raten. SchemaLock fixiert den SHA-256 des eingefrorenen Schemas in der CI, sodass das Format nicht ohne Versionserhöhung abdriften kann. Genau das erlaubt es externen Systemen, sicher gegen das JSON zu bauen: Der Vertrag bewegt sich nur, wenn sich die Version bewegt. Die Ausgabe bleibt portabel — dokumentierte, versionierte Daten, die Ihnen gehören, keine Form, die sich unter Ihnen verschiebt.

Entwurfshintergrund: Open Core, kein Lock-in.

API-Oberfläche

Class	Responsibility
InteropResultInterface	Gemeinsamer Serialisierungsvertrag.
DocumentInfo, PageInfo, BoundingBox	Gemeinsame Dokument-/Seiten-DTOs.
ExtractedText, ExtractedPage, TextBlock	Textextraktions-DTOs.
DocumentSegmentation, Segment	Dokumentsegmentierungs-DTOs.
FormData, FormField	Formulardaten-DTOs.
SchemaLock	CI-Absicherung gegen Schema-Drift.

Codebeispiel — Schnellstart

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

Codebeispiel — Produktion

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);

Randfälle & Fallstricke

• toArray() enthält stets schema_version; nachgelagerte Konsumenten sollten anhand dessen verzweigen.
• SchemaLock::verify() gibt false zurück, wenn die Schema-Datei fehlt oder verändert ist.
• Die DTOs sind schreibgeschützte Sichten; sie führen die Analyse nicht erneut aus.

Performance

Die Serialisierung ist linear in der Größe des Ergebnisgraphen.

Sicherheitshinweise

DTOs tragen nur die Analyseausgabe, die Sie befüllen. Während der Serialisierung erfolgt kein Dateisystem- oder Netzwerk-I/O.

Konformität

Interop definiert ein NextPDF-eigenes versioniertes Schema; es implementiert keinen externen Standard.

Verhaltensvertrag

• Jedes Ergebnis-DTO implementiert InteropResultInterface und serialisiert zu einem JSON-sicheren Array, das stets einen schema_version-Schlüssel trägt, sowie zu einem JSON-String.
• Ergebnis-DTOs (DocumentInfo, PageInfo, BoundingBox, ExtractedText/ExtractedPage/TextBlock, DocumentSegmentation/Segment, FormData/FormField) sind unveränderliche schreibgeschützte Sichten; sie führen die Analyse nicht erneut aus.
• SchemaLock::verify() hält den SHA-256 des eingefrorenen Schemas und gibt false zurück, wenn die Schema-Datei fehlt oder verändert ist, sodass der Wire-Vertrag nicht stillschweigend abdriften kann.
• Die Oberfläche ist explizit versioniert (SCHEMA_VERSION): additive Änderungen erhöhen das Schema; brechende Änderungen erfordern eine neue Major-Version.
• Während der Serialisierung erfolgt kein Dateisystem- oder Netzwerk-I/O.

Hinweis zur Enterprise-Abgrenzung

Enterprise ändert das Interop-Verhalten nicht. Enterprise ergänzt Funktionen höherer Stufe, die separat dokumentiert sind; sie sind zur Nutzung der versionierten Ergebnis-DTOs nicht erforderlich.

Core-Rückfalloption / Alternative

Für schema-gesperrte, versionierte Ergebnis-DTOs gibt es kein Core-Äquivalent. Dies ist eine Pro-Ergänzung.

Veröffentlichungsgrenze

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

Siehe auch

• Extraction — erzeugt Text- und Segmentergebnisse.
• Form — erzeugt Formulardaten-Ergebnisse.
• Interop — Deep Reference — vollständige DTO-Feldreferenz.