Pro edizione

Interop — Riferimento approfondito

In sintesi

Questa pagina è il riferimento a livello di contratto per NextPDF\Pro\Interop\V1. Il modulo contiene quattordici simboli pubblici: un contratto di serializzazione (InteropResultInterface), una guardia di integrità per la CI (SchemaLock), tre DTO di risultato di primo livello (ExtractedText, DocumentSegmentation, FormData) e nove value object ed enum di supporto. Ogni DTO è una vista immutabile e serializzabile in JSON di un singolo risultato di analisi. La forma sul filo è versionata e bloccata; nulla su questa superficie riesegue l’analisi. La vista orientata alle attività si trova nella pagina della capacità.

Disponibilità e licenza

Questa capacità è distribuita in NextPDF Pro (nextpdf/pro) e si attiva con un envelope di licenza di livello Pro. Un deployment privo di quel diritto non carica le classi della capacità. Confronta le edizioni e ottieni una licenza.

Nessun flag di capacità a runtime applica un gate a questo modulo. Le classi sono disponibili ogni volta che nextpdf/pro è installato e provvisto di licenza.

Superficie API pubblica

Simbolo	Parametri	Comportamento predefinito	Restituisce	Solleva o fallisce con	Note
`InteropResultInterface`	—	Contratto per i DTO di risultato di primo livello; estende `JsonSerializable`	—	Non solleva eccezioni	`SCHEMA_VERSION` è la stringa `'1.0'`.
`InteropResultInterface::toArray()`	nessuno	Serializza in un array JSON-safe che porta sempre `schema_version`	`array<string, mixed>`	Non solleva eccezioni	Le implementazioni emettono anche un discriminatore `type`.
`InteropResultInterface::toJson()`	`int $flags = 0`	Codifica l’output di `toArray()`; `JSON_THROW_ON_ERROR` è sempre applicato in OR	`string`	`JsonException` su dati non codificabili	Passare flag come `JSON_PRETTY_PRINT`.
`SchemaLock::verify()`	nessuno	Calcola l’hash del `schema.json` V1 su disco e lo confronta con lo SHA-256 bloccato	`bool`	Non solleva eccezioni	`false` quando il file dello schema è mancante, illeggibile o modificato.
`SchemaLock::expectedHash()`	nessuno	Restituisce l’hash bloccato	`string`	Non solleva eccezioni	Output diagnostico per il triage dei fallimenti CI.
`SchemaLock::actualHash()`	nessuno	Restituisce l’hash del file dello schema corrente	`string`	Non solleva eccezioni	Le stringhe sentinella `FILE_NOT_FOUND` / `READ_FAILED` sostituiscono l’hash in caso di errore di I/O.
`BoundingBox`	`float $x`, `float $y`, `float $width`, `float $height`	Box immutabile in punti dello spazio utente PDF, origine in basso a sinistra	—	Non solleva eccezioni	`area()`, `overlaps()`, `toArray()`, `fromArray()`.
`DocumentInfo`	`int $pageCount` più sei campi di metadati opzionali	Metadati di documento immutabili	—	Non solleva eccezioni	`fromArray()` applica un type-guard a ogni campo; i campi assenti ricadono sui valori predefiniti.
`PageInfo`	`int $pageNumber`, `float $width`, `float $height`, `int $rotation = 0`	Metadati di pagina immutabili	—	Non solleva eccezioni	`isLandscape()`; `fromArray()` converte stringhe numeriche e float.
`ExtractedText`	`list<ExtractedPage> $pages`, `DocumentInfo $documentInfo`, `float $processingTimeMs = 0.0`	Risultato di estrazione testo dell’intero documento	—	`JsonException` solo da `toJson()`	`page()`, `totalBlockCount()`, `plainText()`, `fromArray()`.
`ExtractedPage`	`PageInfo $pageInfo`, `list<TextBlock> $textBlocks`	Contenitore per pagina di blocchi di testo in ordine di lettura	—	Non solleva eccezioni	`plainText()` unisce il contenuto dei blocchi con spazi singoli.
`TextBlock`	`string $content`, `BoundingBox $boundingBox`, `int $pageNumber`, `string $fontName = ''`, `float $fontSize = 0.0`	Sequenza di testo contigua e posizionata	—	Non solleva eccezioni	Nome e dimensione del font sono best-effort (font dominante nel blocco).
`DocumentSegmentation`	`list<Segment> $segments`, `DocumentInfo $documentInfo`, `float $processingTimeMs = 0.0`	Risultato di segmentazione consapevole del layout	—	`JsonException` solo da `toJson()`	`segmentCount()`, `ofType()`, `onPage()`, `contentSegments()`, `fromArray()`.
`Segment`	`SegmentType $type`, `string $content`, `BoundingBox $boundingBox`, `int $pageNumber`, `float $confidence = 1.0`, `list<Segment> $children = []`	Regione di pagina classificata; i figli si annidano ricorsivamente	—	Non solleva eccezioni	La soglia di `isHighConfidence()` è 0.8; `descendantCount()` è ricorsivo.
`SegmentType`	enum con backing string	Dodici casi, da `heading` a `unknown`	—	Non solleva eccezioni	`isContent()` e `isStructural()` partizionano i casi.
`FormData`	`list<FormField> $fields`, `DocumentInfo $documentInfo`, `float $processingTimeMs = 0.0`	Risultato di estrazione moduli dell’intero documento	—	`JsonException` solo da `toJson()`	`field()`, `dataFields()`, `filledCount()`, `toKeyValueMap()`, `fromArray()`.
`FormField`	`string $name`, `FormFieldType $type`, più sei campi opzionali	Singolo campo modulo estratto	—	Non solleva eccezioni	`isFilled()` è `value !== ''`.
`FormFieldType`	enum con backing string	Otto casi, da `text` a `button`	—	Non solleva eccezioni	`isDataField()` è `false` per `button` e `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

Contratto di comportamento

Envelope versionato. Ogni DTO di primo livello (ExtractedText, DocumentSegmentation, FormData) implementa InteropResultInterface. Il suo output toArray() porta sempre schema_version ('1.0') e un discriminatore type: extracted_text, document_segmentation o form_data.
Codifica JSON. toJson() delega a json_encode con JSON_THROW_ON_ERROR applicato in OR ai flag del chiamante. jsonSerialize() delega a toArray(), quindi json_encode($dto) produce la stessa forma.
Serializzazione deterministica. L’ordine e la forma delle chiavi sono fissati dal DTO. Segment::toArray() omette la chiave children quando è vuota; FormField::toArray() omette bounding_box quando è null. I consumatori devono trattare entrambe le chiavi come opzionali.
Round trip. Ogni DTO espone un metodo statico fromArray() che accetta un oggetto JSON decodificato. I campi sono type-guarded a questo confine tra processi: i valori assenti o con tipo errato ricadono sui valori predefiniti documentati invece di sollevare eccezioni.
Fallback degli enum. Una stringa type non riconosciuta viene mappata su SegmentType::Unknown in Segment::fromArray() e su FormFieldType::Text in FormField::fromArray().
Coordinate. Le coordinate di BoundingBox sono unità dello spazio utente PDF (punti, 1/72 di pollice) con l’origine nell’angolo in basso a sinistra della pagina. I numeri di pagina sono a base uno ovunque.
Unioni in testo semplice. ExtractedPage::plainText() unisce il contenuto dei blocchi con spazi singoli. ExtractedText::plainText() unisce le pagine con righe vuote ("\n\n").
Query di segmentazione. ofType(), onPage() e contentSegments() filtrano solo i segmenti di primo livello e restituiscono liste re-indicizzate. contentSegments() seleziona i tipi per cui SegmentType::isContent() è true: heading, sub_heading, paragraph, table, list, code.
Query sui moduli. FormData::dataFields() e toKeyValueMap() escludono i tipi di campo non-dati (button, signature). filledCount() conta i campi il cui valore è una stringa non vuota.
Lock dello schema. SchemaLock::verify() legge il schema.json V1 distribuito con il pacchetto, normalizza CRLF in LF, calcola l’hash con SHA-256 e lo confronta con la costante bloccata a tempo costante. La CI lo utilizza per bloccare la deriva silenziosa dello schema; il valore del lock cambia solo con una modifica dello schema deliberata e versionata.
Politica di versionamento. La superficie V1 è un contratto pubblico esplicito. Le modifiche additive incrementano la versione dello schema; le modifiche che rompono la compatibilità richiedono una nuova versione major.

Casi limite e modalità di guasto

L’unico membro che solleva eccezioni su questa superficie è toJson(): JsonException quando l’array non è codificabile, per esempio in caso di UTF-8 non valido nel contenuto estratto.
SchemaLock::verify() restituisce false — non solleva mai eccezioni — quando il file dello schema è mancante, illeggibile o modificato. Confrontare expectedHash() con actualHash() per distinguere la deriva da un errore di I/O.
I fallback di fromArray() sono silenziosi per progettazione. Un page_number con tipo errato diventa 1; un confidence con tipo errato diventa il valore predefinito. Validare a monte quando i valori predefiniti fabbricati non sono accettabili.
La coercizione da stringa numerica è asimmetrica. PageInfo::fromArray() accetta stringhe numeriche per i suoi campi int e float; Segment e TextBlock accettano solo int o float per confidence e font_size.
BoundingBox::fromArray() richiede tutte e quattro le chiavi secondo la forma dell’array documentata. I DTO che lo incorporano sostituiscono un box a zero (o null per FormField) quando la chiave wrapper è assente.
ExtractedPage::fromArray() sostituisce un page_info di fallback pari a pagina 1 a 595 × 842 punti quando la chiave è mancante o con tipo errato.
FormField::fromArray() accetta solo booleani stretti per required e read_only; stringhe e interi truthy vengono mappati su false.
I figli di Segment ricorrono senza limite di profondità. L’annidamento estremamente profondo è vincolato solo dai limiti di memoria e stack di PHP.
Nessuna operazione di chiave crittografica o di firma avviene in questo modulo. SchemaLock usa SHA-256 unicamente come checksum di integrità del file, quindi non vi è alcun comportamento specifico della modalità FIPS.

Conformità

Interop V1 è un contratto sul filo versionato di proprietà di NextPDF. Non implementa uno standard esterno, quindi non esiste una tabella di citazioni normative. La semantica di BoundingBox si allinea al modello di coordinate dello spazio utente PDF utilizzato dai sottosistemi Core produttori; si tratta di un’affermazione di allineamento strutturale, non di un risultato di test di conformità. NextPDF non detiene alcuna certificazione e non ne concede alcuna.

Note di sviluppo

Ramificare su schema_version nei consumatori. Trattare le chiavi additive come compatibili; rifiutare esplicitamente le versioni major sconosciute.
Eseguire SchemaLock::verify() nella CI. In caso di fallimento, registrare expectedHash() e actualHash() e richiedere una modifica dello schema deliberata e versionata, mai una modifica in-place.
Per i round trip tra processi, decodificare con array associativi (json_decode($json, true)) e passare il risultato al fromArray() corrispondente.
Tutti i DTO sono final e readonly. Estendere per composizione; derivare nuove viste dai campi pubblici.
toKeyValueMap() appiattisce solo i campi portatori di dati. Leggere i campi signature direttamente da FormData::$fields quando la loro presenza è rilevante.
Il riutilizzo è sicuro: i DTO non contengono stato mutabile né risorse, quindi possono essere memorizzati in cache, condivisi tra le richieste e serializzati ripetutamente.

Confine di pubblicazione

Questa pagina documenta solo il comportamento osservabile esternamente e la superficie API pubblica supportata. I percorsi di namespace interni, le classi helper, le tabelle dei meccanismi, i nomi dei file di runbook e i prefissi dei ticket sono fuori ambito.