Pro editie

Interop — Diepe referentie

In één oogopslag

Deze pagina is de contract-niveau referentie voor NextPDF\Pro\Interop\V1. De module bevat veertien publieke symbolen: één serialisatiecontract (InteropResultInterface), één CI-integriteitsbewaker (SchemaLock), drie top-level resultaat-DTO’s (ExtractedText, DocumentSegmentation, FormData) en negen ondersteunende value objects en enums. Elke DTO is een onveranderlijke, JSON-serialiseerbare weergave van één analyseresultaat. De wire-vorm is geversioneerd en vergrendeld; niets op dit oppervlak voert de analyse opnieuw uit. De taakgerichte weergave staat op de capabilitypagina.

Beschikbaarheid en licenties

Deze capability wordt geleverd in NextPDF Pro (nextpdf/pro) en activeert met een Pro-tier licentie-envelope. Een deployment zonder die entitlement laadt de klassen van de capability niet. Vergelijk edities en vraag een licentie aan.

Geen runtime capability-flag gate’t deze module. De klassen zijn beschikbaar zodra nextpdf/pro is geïnstalleerd en gelicentieerd.

Publiek API-oppervlak

Symbool	Parameters	Standaardgedrag	Retourneert	Gooit of faalt met	Opmerkingen
`InteropResultInterface`	—	Contract voor top-level resultaat-DTO’s; breidt `JsonSerializable` uit	—	Gooit niet	`SCHEMA_VERSION` is de string `'1.0'`.
`InteropResultInterface::toArray()`	geen	Serialiseert naar een JSON-veilige array die altijd `schema_version` bevat	`array<string, mixed>`	Gooit niet	Implementaties zenden ook een `type`-discriminator uit.
`InteropResultInterface::toJson()`	`int $flags = 0`	Codeert de output van `toArray()`; `JSON_THROW_ON_ERROR` wordt altijd erbij ge-OR’d	`string`	`JsonException` bij niet-codeerbare data	Geef flags door zoals `JSON_PRETTY_PRINT`.
`SchemaLock::verify()`	geen	Hasht de V1 `schema.json` op schijf en vergelijkt deze met de vastgelegde SHA-256	`bool`	Gooit niet	`false` wanneer het schemabestand ontbreekt, onleesbaar is of gewijzigd.
`SchemaLock::expectedHash()`	geen	Retourneert de vastgelegde hash	`string`	Gooit niet	Diagnostische output voor CI-faaltriage.
`SchemaLock::actualHash()`	geen	Retourneert de hash van het huidige schemabestand	`string`	Gooit niet	Sentinel-strings `FILE_NOT_FOUND` / `READ_FAILED` vervangen de hash bij een I/O-fout.
`BoundingBox`	`float $x`, `float $y`, `float $width`, `float $height`	Onveranderlijke box in PDF user-space-punten, oorsprong linksonder	—	Gooit niet	`area()`, `overlaps()`, `toArray()`, `fromArray()`.
`DocumentInfo`	`int $pageCount` plus zes optionele metadatavelden	Onveranderlijke documentmetadata	—	Gooit niet	`fromArray()` type-guardt elk veld; ontbrekende velden vallen terug op standaardwaarden.
`PageInfo`	`int $pageNumber`, `float $width`, `float $height`, `int $rotation = 0`	Onveranderlijke paginametadata	—	Gooit niet	`isLandscape()`; `fromArray()` dwingt numerieke strings en floats af.
`ExtractedText`	`list<ExtractedPage> $pages`, `DocumentInfo $documentInfo`, `float $processingTimeMs = 0.0`	Tekstextractieresultaat voor het hele document	—	`JsonException` alleen uit `toJson()`	`page()`, `totalBlockCount()`, `plainText()`, `fromArray()`.
`ExtractedPage`	`PageInfo $pageInfo`, `list<TextBlock> $textBlocks`	Container per pagina van tekstblokken in leesvolgorde	—	Gooit niet	`plainText()` voegt blokinhoud samen met enkele spaties.
`TextBlock`	`string $content`, `BoundingBox $boundingBox`, `int $pageNumber`, `string $fontName = ''`, `float $fontSize = 0.0`	Gepositioneerde aaneengesloten tekstrun	—	Gooit niet	Fontnaam en -grootte zijn best-effort (dominante font in het blok).
`DocumentSegmentation`	`list<Segment> $segments`, `DocumentInfo $documentInfo`, `float $processingTimeMs = 0.0`	Layout-bewust segmentatieresultaat	—	`JsonException` alleen uit `toJson()`	`segmentCount()`, `ofType()`, `onPage()`, `contentSegments()`, `fromArray()`.
`Segment`	`SegmentType $type`, `string $content`, `BoundingBox $boundingBox`, `int $pageNumber`, `float $confidence = 1.0`, `list<Segment> $children = []`	Geclassificeerde paginaregio; kinderen nesten recursief	—	Gooit niet	`isHighConfidence()`-drempel is 0.8; `descendantCount()` is recursief.
`SegmentType`	string-backed enum	Twaalf cases, `heading` tot en met `unknown`	—	Gooit niet	`isContent()` en `isStructural()` verdelen de cases.
`FormData`	`list<FormField> $fields`, `DocumentInfo $documentInfo`, `float $processingTimeMs = 0.0`	Formulierextractieresultaat voor het hele document	—	`JsonException` alleen uit `toJson()`	`field()`, `dataFields()`, `filledCount()`, `toKeyValueMap()`, `fromArray()`.
`FormField`	`string $name`, `FormFieldType $type`, plus zes optionele velden	Enkel geëxtraheerd formulierveld	—	Gooit niet	`isFilled()` is `value !== ''`.
`FormFieldType`	string-backed enum	Acht cases, `text` tot en met `button`	—	Gooit niet	`isDataField()` is `false` voor `button` en `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

Gedragscontract

Geversioneerde envelope. Elke top-level DTO (ExtractedText, DocumentSegmentation, FormData) implementeert InteropResultInterface. De output van toArray() bevat altijd schema_version ('1.0') en een type-discriminator: extracted_text, document_segmentation of form_data.
JSON-codering. toJson() delegeert naar json_encode met JSON_THROW_ON_ERROR bij de flags van de aanroeper ge-OR’d. jsonSerialize() delegeert naar toArray(), dus json_encode($dto) produceert dezelfde vorm.
Deterministische serialisatie. Sleutelvolgorde en vorm liggen vast in de DTO. Segment::toArray() laat de sleutel children weg als deze leeg is; FormField::toArray() laat bounding_box weg als deze null is. Consumenten moeten beide sleutels als optioneel behandelen.
Round trip. Elke DTO biedt een statische fromArray() die een gedecodeerd JSON-object accepteert. Velden worden type-guarded op deze cross-process-grens: ontbrekende of verkeerd getypeerde waarden vallen terug op gedocumenteerde standaardwaarden in plaats van te gooien.
Enum-fallbacks. Een niet-herkende type-string mapt naar SegmentType::Unknown in Segment::fromArray() en naar FormFieldType::Text in FormField::fromArray().
Coördinaten. BoundingBox-coördinaten zijn PDF user-space-eenheden (punten, 1/72 inch) met de oorsprong in de linkeronderhoek van de pagina. Paginanummers zijn overal één-gebaseerd.
Plain-text joins. ExtractedPage::plainText() voegt blokinhoud samen met enkele spaties. ExtractedText::plainText() voegt pagina’s samen met lege regels ("\n\n").
Segmentatiequery’s. ofType(), onPage() en contentSegments() filteren alleen top-level segmenten en retourneren opnieuw geïndexeerde lijsten. contentSegments() selecteert de types waar SegmentType::isContent() true is: heading, sub_heading, paragraph, table, list, code.
Formulierquery’s. FormData::dataFields() en toKeyValueMap() sluiten niet-datavelden uit (button, signature). filledCount() telt velden waarvan de waarde een niet-lege string is.
Schemalock. SchemaLock::verify() leest de V1 schema.json die met het pakket wordt meegeleverd, normaliseert CRLF naar LF, hasht met SHA-256 en vergelijkt in constante tijd met de vastgelegde constante. CI gebruikt het om stilzwijgende schemadrift te blokkeren; de lock-waarde verandert alleen bij een bewuste, geversioneerde schemawijziging.
Versioneringsbeleid. Het V1-oppervlak is een expliciet publiek contract. Additieve wijzigingen verhogen de schemaversie; breaking changes vereisen een nieuwe major-versie.

Randgevallen en faalmodi

Het enige lid dat op dit oppervlak gooit is toJson(): JsonException wanneer de array niet codeerbaar is, bijvoorbeeld ongeldige UTF-8 in geëxtraheerde inhoud.
SchemaLock::verify() retourneert false — gooit nooit — wanneer het schemabestand ontbreekt, onleesbaar is of gewijzigd. Vergelijk expectedHash() met actualHash() om drift van een I/O-fout te onderscheiden.
fromArray()-fallbacks zijn stilzwijgend van opzet. Een verkeerd getypeerde page_number wordt 1; een verkeerd getypeerde confidence wordt de standaardwaarde. Valideer upstream wanneer verzonnen standaardwaarden onacceptabel zijn.
Numerieke-string-coercie is asymmetrisch. PageInfo::fromArray() accepteert numerieke strings voor zijn int- en float-velden; Segment en TextBlock accepteren alleen int of float voor confidence en font_size.
BoundingBox::fromArray() vereist alle vier de sleutels volgens de gedocumenteerde array-vorm. De DTO’s die het insluiten vervangen deze door een nul-box (of null voor FormField) wanneer de wrapper-sleutel ontbreekt.
ExtractedPage::fromArray() vervangt door een fallback-page_info van pagina 1 op 595 × 842 punten wanneer de sleutel ontbreekt of verkeerd getypeerd is.
FormField::fromArray() accepteert alleen strikte booleans voor required en read_only; truthy strings en integers mappen naar false.
Segment-kinderen recursen zonder dieptelimiet. Extreem diepe nesting wordt alleen begrensd door PHP’s geheugen- en stacklimieten.
Er vindt geen cryptografische sleutel- of handtekeningbewerking plaats in deze module. SchemaLock gebruikt SHA-256 uitsluitend als bestandsintegriteits-checksum, dus er is geen FIPS-modus-specifiek gedrag.

Conformiteit

Interop V1 is een door NextPDF beheerd, geversioneerd wire-contract. Het implementeert geen externe standaard, dus er is geen normatieve citaattabel. De semantiek van BoundingBox sluit aan bij het PDF user-space-coördinatenmodel dat de producerende Core-subsystemen gebruiken; dat is een uitspraak over structurele afstemming, geen conformiteitstestresultaat. NextPDF heeft geen certificering en verleent er geen.

Ontwikkelnotities

Vertak op schema_version in consumenten. Behandel additieve sleutels als compatibel; wijs onbekende major-versies expliciet af.
Voer SchemaLock::verify() uit in CI. Log bij een fout expectedHash() en actualHash() en eis een bewuste, geversioneerde schemawijziging, nooit een in-place bewerking.
Decodeer voor cross-process round trips met associatieve arrays (json_decode($json, true)) en voer het resultaat naar de bijbehorende fromArray().
Alle DTO’s zijn final en readonly. Breid uit via compositie; leid nieuwe weergaven af uit de publieke velden.
toKeyValueMap() plat alleen data-dragende velden af. Lees signature-velden rechtstreeks uit FormData::$fields wanneer hun aanwezigheid van belang is.
Hergebruik is veilig: de DTO’s houden geen veranderlijke staat en geen resources vast, dus ze kunnen worden gecachet, gedeeld over requests en herhaaldelijk geserialiseerd.

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.