Interoperabilità

In breve

NextPDF Pro fornisce un insieme versionato di data-transfer object (DTO) di risultato che serializzano l’output dell’analisi PDF — informazioni sul documento, pagine, blocchi di testo, segmentazione e dati di modulo — in una forma JSON stabile e bloccata da schema, per il consumo da parte di sistemi e strumenti esterni.

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 tale entitlement non carica le classi della capacità. Interop fa parte dell’edizione Pro; non esiste un flag di licenza separato per funzionalità. Confronta le edizioni e ottieni una licenza.

Installazione

composer require nextpdf/pro:^3

Panoramica concettuale

Quando l’output dell’elaborazione PDF attraversa un confine di processo o di servizio, il destinatario ha bisogno di un contratto stabile. La superficie Interop V1 lo fornisce:

• InteropResultInterface — ogni DTO di risultato la implementa. Ciascuno serializza in un array JSON-safe che porta sempre una chiave schema_version, e in una stringa JSON.
• DTO di risultato — DocumentInfo, PageInfo, BoundingBox, ExtractedText / ExtractedPage / TextBlock, DocumentSegmentation / Segment e FormData / FormField. Ciascuno è una vista immutabile di un risultato di analisi.
• SchemaLock — un guard di CI. Detiene lo SHA-256 dello schema congelato e fa fallire la build se il file di schema cambia senza un corrispondente incremento di versione, così che il contratto di trasmissione non possa derivare silenziosamente.

La superficie Interop è esplicitamente versionata (SCHEMA_VERSION). Trattarla come un contratto di API pubblica: le modifiche additive incrementano lo schema; le modifiche con rottura di compatibilità richiedono una nuova versione principale.

Perché funziona così

La forma di serializzazione è trattata come un contratto di API pubblica, non come un dettaglio implementativo. Ogni DTO porta una chiave schema_version, così che i consumatori si diramino sulla forma che ricevono anziché indovinarla. SchemaLock fissa in CI lo SHA-256 dello schema congelato, così che il formato non possa derivare senza un incremento di versione. È questo che consente ai sistemi esterni di costruire in sicurezza sul JSON: il contratto si muove solo quando si muove la versione. L’output resta portabile — dati documentati e versionati di tua proprietà, non una forma che cambia sotto di te.

Contesto di progettazione: Open core, senza lock-in.

Superficie API

Classe	Responsabilità
InteropResultInterface	Contratto di serializzazione comune.
DocumentInfo, PageInfo, BoundingBox	DTO comuni di documento/pagina.
ExtractedText, ExtractedPage, TextBlock	DTO di estrazione del testo.
DocumentSegmentation, Segment	DTO di segmentazione del documento.
FormData, FormField	DTO di dati di modulo.
SchemaLock	Guard di CI contro la deriva dello schema.

Esempio di codice — Avvio rapido

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

Esempio di codice — Produzione

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

Casi limite e insidie

• toArray() include sempre schema_version; i consumatori a valle dovrebbero diramarsi su di esso.
• SchemaLock::verify() restituisce false se il file di schema è mancante o modificato.
• I DTO sono viste in sola lettura; non rieseguono l’analisi.

Prestazioni

La serializzazione è lineare rispetto alla dimensione del grafo del risultato.

Note di sicurezza

I DTO portano solo l’output dell’analisi che l’utente popola. Durante la serializzazione non si verifica alcun I/O di filesystem o di rete.

Conformità

Interop definisce uno schema versionato di proprietà di NextPDF; non implementa uno standard esterno.

Contratto di comportamento

• Ogni DTO di risultato implementa InteropResultInterface e serializza in un array JSON-safe che porta sempre una chiave schema_version, e in una stringa JSON.
• I DTO di risultato (DocumentInfo, PageInfo, BoundingBox, ExtractedText/ExtractedPage/TextBlock, DocumentSegmentation/Segment, FormData/FormField) sono viste immutabili in sola lettura; non rieseguono l’analisi.
• SchemaLock::verify() detiene lo SHA-256 dello schema congelato e restituisce false se il file di schema è mancante o modificato, così che il contratto di trasmissione non possa derivare silenziosamente.
• La superficie è esplicitamente versionata (SCHEMA_VERSION): le modifiche additive incrementano lo schema; le modifiche con rottura di compatibilità richiedono una nuova versione principale.
• Durante la serializzazione non si verifica alcun I/O di filesystem o di rete.

Nota sul confine Enterprise

Enterprise non modifica il comportamento di Interop. Enterprise aggiunge funzionalità di fascia superiore documentate separatamente; non sono richieste per usare i DTO di risultato versionati.

Fallback / alternativa Core

Non esiste alcun equivalente Core per DTO di risultato versionati e bloccati da schema. Questa è un’aggiunta di Pro.

Confine di pubblicazione

Questa pagina documenta solo il comportamento osservabile dall’esterno e la superficie di API pubblica supportata. Percorsi di namespace interni, classi helper, tabelle di meccanismi, nomi di file di runbook e prefissi di ticket sono fuori ambito.

Vedere anche

• Extraction — produce risultati di testo e segmenti.
• Form — produce risultati di dati di modulo.
• Interop — Deep Reference — riferimento completo dei campi DTO.