Interop

In het kort

NextPDF Pro biedt een geversioneerde set result-data-transfer-objects (DTO’s) die de PDF-analyse-uitvoer — documentinfo, pagina’s, tekstblokken, segmentatie en formuliergegevens — serialiseren naar een stabiele, schema-vergrendelde JSON-vorm voor consumptie door externe systemen en tools.

Beschikbaarheid en licentie

Deze mogelijkheid wordt geleverd in NextPDF Pro (nextpdf/pro) en wordt geactiveerd met een licentie-envelop van het Pro-niveau. Een deployment zonder die entitlement laadt de klassen van de mogelijkheid niet. Interop maakt deel uit van de Pro-editie; er is geen aparte licentievlag per functie. Vergelijk edities en vraag een licentie aan.

Installatie

composer require nextpdf/pro:^3

Conceptueel overzicht

Wanneer PDF-verwerkingsuitvoer een proces- of servicegrens passeert, heeft de ontvanger een stabiel contract nodig. Het Interop V1-oppervlak biedt dat:

• InteropResultInterface — elke result-DTO implementeert deze. Elke serialiseert naar een JSON-veilige array die altijd een schema_version-sleutel draagt, en naar een JSON-string.
• Result-DTO’s — DocumentInfo, PageInfo, BoundingBox, ExtractedText / ExtractedPage / TextBlock, DocumentSegmentation / Segment, en FormData / FormField. Elke is een immutable weergave van één analyseresultaat.
• SchemaLock — een CI-bewaking. Deze houdt de SHA-256 van het bevroren schema vast en laat de build falen als het schemabestand wijzigt zonder een bijbehorende versieverhoging, zodat het wire-contract niet stilzwijgend kan afdrijven.

Het Interop-oppervlak is expliciet geversioneerd (SCHEMA_VERSION). Behandel het als een publiek API-contract: additieve wijzigingen verhogen het schema; brekende wijzigingen vereisen een nieuwe grote versie.

Waarom het zo werkt

De serialisatievorm wordt behandeld als een publiek API-contract, niet als een implementatiedetail. Elke DTO draagt een schema_version-sleutel, zodat consumenten vertakken op de vorm die ze ontvangen in plaats van te gokken. SchemaLock verankert de SHA-256 van het bevroren schema in CI, zodat het formaat niet kan afdrijven zonder een versieverhoging. Dat is wat externe systemen in staat stelt om veilig tegen de JSON te bouwen: het contract beweegt alleen mee wanneer de versie dat doet. De uitvoer blijft portabel — gedocumenteerde, geversioneerde data die je zelf bezit, geen vorm die onder je vandaan verschuift.

Ontwerpachtergrond: Open core, geen lock-in.

API-oppervlak

Klasse	Verantwoordelijkheid
InteropResultInterface	Gemeenschappelijk serialisatiecontract.
DocumentInfo, PageInfo, BoundingBox	Gemeenschappelijke document-/pagina-DTO’s.
ExtractedText, ExtractedPage, TextBlock	Tekstextractie-DTO’s.
DocumentSegmentation, Segment	Documentsegmentatie-DTO’s.
FormData, FormField	Formuliergegevens-DTO’s.
SchemaLock	CI-bewaking voor schema-afdrijving.

Codevoorbeeld — Snelstart

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

Codevoorbeeld — Productie

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

Randgevallen en valkuilen

• toArray() bevat altijd schema_version; stroomafwaartse consumenten moeten erop vertakken.
• SchemaLock::verify() retourneert false als het schemabestand ontbreekt of is gewijzigd.
• De DTO’s zijn alleen-lezen weergaven; ze voeren de analyse niet opnieuw uit.

Prestaties

Serialisatie is lineair in de grootte van de resultaatgraaf.

Beveiligingsnotities

DTO’s dragen alleen de analyse-uitvoer die jij vult. Er treedt geen bestandssysteem- of netwerk-I/O op tijdens serialisatie.

Conformiteit

Interop definieert een door NextPDF beheerd geversioneerd schema; het implementeert geen externe standaard.

Gedragscontract

• Elke result-DTO implementeert InteropResultInterface en serialiseert naar een JSON-veilige array die altijd een schema_version-sleutel draagt, en naar een JSON-string.
• Result-DTO’s (DocumentInfo, PageInfo, BoundingBox, ExtractedText/ExtractedPage/TextBlock, DocumentSegmentation/Segment, FormData/FormField) zijn immutable alleen-lezen weergaven; ze voeren de analyse niet opnieuw uit.
• SchemaLock::verify() houdt de SHA-256 van het bevroren schema vast en retourneert false als het schemabestand ontbreekt of is gewijzigd, zodat het wire-contract niet stilzwijgend kan afdrijven.
• Het oppervlak is expliciet geversioneerd (SCHEMA_VERSION): additieve wijzigingen verhogen het schema; brekende wijzigingen vereisen een nieuwe grote versie.
• Er treedt geen bestandssysteem- of netwerk-I/O op tijdens serialisatie.

Enterprise-grensnotitie

Enterprise verandert het Interop-gedrag niet. Enterprise voegt hoger-niveau functies toe die apart worden gedocumenteerd; ze zijn niet vereist om de geversioneerde result-DTO’s te gebruiken.

Core-fallback / alternatief

Er is geen Core-equivalent voor schema-vergrendelde, geversioneerde result-DTO’s. Dit is een Pro-toevoeging.

Publicatiegrens

Deze pagina documenteert alleen extern waarneembaar gedrag en het ondersteunde publieke API-oppervlak. Interne namespace-paden, helperklassen, mechanismetabellen, runbook-bestandsnamen en ticketprefixen vallen buiten de scope.

Zie ook

• Extraction — produceert tekst- en segmentresultaten.
• Form — produceert formuliergegevensresultaten.
• Interop — Diepe referentie — volledige DTO-veldreferentie.