Interopérabilité

En bref

NextPDF Pro fournit un ensemble versionné d’objets de transfert de données (DTO) de résultat qui sérialisent la sortie d’analyse PDF — informations de document, pages, blocs de texte, segmentation et données de formulaire — vers une forme JSON stable et verrouillée par schéma, destinée à être consommée par des systèmes et des outils externes.

Disponibilité et licence

Cette capacité est fournie dans NextPDF Pro (nextpdf/pro) et s’active avec une enveloppe de licence de niveau Pro. Un déploiement dépourvu de cette autorisation ne charge pas les classes de la capacité. Interop fait partie de l’édition Pro ; il n’existe aucun indicateur de licence distinct par fonctionnalité. Compare les éditions et obtiens une licence.

Installation

composer require nextpdf/pro:^3

Aperçu conceptuel

Lorsque la sortie de traitement PDF franchit une frontière de processus ou de service, le récepteur a besoin d’un contrat stable. La surface Interop V1 le fournit :

• InteropResultInterface — chaque DTO de résultat l’implémente. Chacun se sérialise vers un tableau compatible JSON qui porte toujours une clé schema_version, et vers une chaîne JSON.
• DTO de résultat — DocumentInfo, PageInfo, BoundingBox, ExtractedText / ExtractedPage / TextBlock, DocumentSegmentation / Segment, et FormData / FormField. Chacun est une vue immuable d’un résultat d’analyse.
• SchemaLock — un garde-fou de CI. Il détient le SHA-256 du schéma figé et fait échouer la build si le fichier de schéma change sans incrément de version correspondant, afin que le contrat de transmission ne puisse pas dériver silencieusement.

La surface Interop est explicitement versionnée (SCHEMA_VERSION). Traite-la comme un contrat d’API publique : les changements additifs incrémentent le schéma ; les changements cassants exigent une nouvelle version majeure.

Pourquoi cela fonctionne ainsi

La forme de sérialisation est traitée comme un contrat d’API publique, et non comme un détail d’implémentation. Chaque DTO porte une clé schema_version, de sorte que les consommateurs se branchent sur la forme qu’ils reçoivent au lieu de la deviner. SchemaLock épingle le SHA-256 du schéma figé dans la CI, afin que le format ne puisse pas dériver sans incrément de version. C’est ce qui permet aux systèmes externes de se construire sur le JSON en toute sécurité : le contrat ne bouge que lorsque la version bouge. La sortie reste portable — des données documentées, versionnées et t’appartenant, et non une forme qui se dérobe sous tes pieds.

Contexte de conception : Open core, no lock-in.

Surface d’API

Classe	Responsabilité
InteropResultInterface	Contrat de sérialisation commun.
DocumentInfo, PageInfo, BoundingBox	DTO communs de document/page.
ExtractedText, ExtractedPage, TextBlock	DTO d’extraction de texte.
DocumentSegmentation, Segment	DTO de segmentation de document.
FormData, FormField	DTO de données de formulaire.
SchemaLock	Garde-fou de CI contre la dérive de schéma.

Exemple de code — Démarrage rapide

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

Exemple de code — Production

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

Cas limites et pièges

• toArray() inclut toujours schema_version ; les consommateurs en aval devraient brancher dessus.
• SchemaLock::verify() renvoie false si le fichier de schéma est manquant ou modifié.
• Les DTO sont des vues en lecture seule ; ils ne relancent pas l’analyse.

Performance

La sérialisation est linéaire par rapport à la taille du graphe de résultat.

Notes de sécurité

Les DTO ne portent que la sortie d’analyse que tu renseignes. Aucune E/S de système de fichiers ou de réseau ne se produit pendant la sérialisation.

Conformité

Interop définit un schéma versionné détenu par NextPDF ; il n’implémente aucune norme externe.

Contrat de comportement

• Chaque DTO de résultat implémente InteropResultInterface et se sérialise vers un tableau compatible JSON qui porte toujours une clé schema_version, et vers une chaîne JSON.
• Les DTO de résultat (DocumentInfo, PageInfo, BoundingBox, ExtractedText/ExtractedPage/TextBlock, DocumentSegmentation/Segment, FormData/FormField) sont des vues immuables en lecture seule ; ils ne relancent pas l’analyse.
• SchemaLock::verify() détient le SHA-256 du schéma figé et renvoie false si le fichier de schéma est manquant ou modifié, afin que le contrat de transmission ne puisse pas dériver silencieusement.
• La surface est explicitement versionnée (SCHEMA_VERSION) : les changements additifs incrémentent le schéma ; les changements cassants exigent une nouvelle version majeure.
• Aucune E/S de système de fichiers ou de réseau ne se produit pendant la sérialisation.

Note de frontière Enterprise

Enterprise ne change pas le comportement d’Interop. Enterprise ajoute des fonctionnalités de niveau supérieur, documentées séparément ; elles ne sont pas requises pour utiliser les DTO de résultat versionnés.

Repli / alternative Core

Il n’existe aucun équivalent Core pour des DTO de résultat versionnés et verrouillés par schéma. C’est un ajout de Pro.

Frontière de publication

Cette page ne documente que le comportement observable de l’extérieur et la surface d’API publique prise en charge. Les chemins d’espaces de noms internes, les classes d’assistance, les tableaux de mécanismes, les noms de fichiers de runbook et les préfixes de tickets sont hors périmètre.

Voir aussi

• Extraction — produit des résultats de texte et de segment.
• Form — produit des résultats de données de formulaire.
• Interop — Référence approfondie — référence complète des champs de DTO.