Interop — Référence détaillée

En un coup d’œil

Cette page est la référence au niveau du contrat pour NextPDF\Pro\Interop\V1. Le module contient quatorze symboles publics : un contrat de sérialisation (InteropResultInterface), une garde d’intégrité CI (SchemaLock), trois DTO de résultat de premier niveau (ExtractedText, DocumentSegmentation, FormData) et neuf value objects et enums de support. Chaque DTO est une vue immuable et sérialisable en JSON d’un unique résultat d’analyse. La forme de transport est versionnée et verrouillée ; rien sur cette surface ne relance l’analyse. La vue orientée tâches se trouve sur la page de capacité.

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 ce droit ne charge pas les classes de la capacité. Compare les éditions et obtiens une licence.

Aucun indicateur de capacité à l’exécution ne restreint ce module. Les classes sont disponibles dès que nextpdf/pro est installé et sous licence.

Surface d’API publique

Symbole	Paramètres	Comportement par défaut	Retour	Lève ou échoue avec	Notes
InteropResultInterface	—	Contrat pour les DTO de résultat de premier niveau ; étend JsonSerializable	—	Ne lève pas	SCHEMA_VERSION est la chaîne '1.0'.
InteropResultInterface::toArray()	aucun	Sérialise vers un tableau compatible JSON qui porte toujours schema_version	array<string, mixed>	Ne lève pas	Les implémentations émettent aussi un discriminant type.
InteropResultInterface::toJson()	int $flags = 0	Encode la sortie de toArray() ; JSON_THROW_ON_ERROR est toujours ajouté par OR	string	JsonException sur des données non encodables	Passe des indicateurs comme JSON_PRETTY_PRINT.
SchemaLock::verify()	aucun	Calcule le hachage du schema.json V1 sur disque et le compare au SHA-256 verrouillé	bool	Ne lève pas	false lorsque le fichier de schéma est absent, illisible ou modifié.
SchemaLock::expectedHash()	aucun	Renvoie le hachage verrouillé	string	Ne lève pas	Sortie de diagnostic pour le triage des échecs CI.
SchemaLock::actualHash()	aucun	Renvoie le hachage du fichier de schéma actuel	string	Ne lève pas	Les chaînes sentinelles FILE_NOT_FOUND / READ_FAILED remplacent le hachage en cas d’échec d’E/S.
BoundingBox	float $x, float $y, float $width, float $height	Boîte immuable en points de l’espace utilisateur PDF, origine en bas à gauche	—	Ne lève pas	area(), overlaps(), toArray(), fromArray().
DocumentInfo	int $pageCount plus six champs de métadonnées optionnels	Métadonnées de document immuables	—	Ne lève pas	fromArray() protège le type de chaque champ ; les champs absents reviennent aux valeurs par défaut.
PageInfo	int $pageNumber, float $width, float $height, int $rotation = 0	Métadonnées de page immuables	—	Ne lève pas	isLandscape() ; fromArray() convertit les chaînes numériques et les flottants.
ExtractedText	list<ExtractedPage> $pages, DocumentInfo $documentInfo, float $processingTimeMs = 0.0	Résultat d’extraction de texte pour tout le document	—	JsonException depuis toJson() uniquement	page(), totalBlockCount(), plainText(), fromArray().
ExtractedPage	PageInfo $pageInfo, list<TextBlock> $textBlocks	Conteneur par page des blocs de texte dans l’ordre de lecture	—	Ne lève pas	plainText() joint le contenu des blocs avec des espaces simples.
TextBlock	string $content, BoundingBox $boundingBox, int $pageNumber, string $fontName = '', float $fontSize = 0.0	Séquence de texte contiguë et positionnée	—	Ne lève pas	Le nom et la taille de police sont au mieux (police dominante du bloc).
DocumentSegmentation	list<Segment> $segments, DocumentInfo $documentInfo, float $processingTimeMs = 0.0	Résultat de segmentation tenant compte de la mise en page	—	JsonException depuis toJson() uniquement	segmentCount(), ofType(), onPage(), contentSegments(), fromArray().
Segment	SegmentType $type, string $content, BoundingBox $boundingBox, int $pageNumber, float $confidence = 1.0, list<Segment> $children = []	Région de page classifiée ; les enfants s’imbriquent récursivement	—	Ne lève pas	Le seuil de isHighConfidence() est 0.8 ; descendantCount() est récursif.
SegmentType	enum adossé à une chaîne	Douze cas, de heading à unknown	—	Ne lève pas	isContent() et isStructural() partitionnent les cas.
FormData	list<FormField> $fields, DocumentInfo $documentInfo, float $processingTimeMs = 0.0	Résultat d’extraction de formulaire pour tout le document	—	JsonException depuis toJson() uniquement	field(), dataFields(), filledCount(), toKeyValueMap(), fromArray().
FormField	string $name, FormFieldType $type, plus six champs optionnels	Champ de formulaire extrait unique	—	Ne lève pas	isFilled() correspond à value !== ''.
FormFieldType	enum adossé à une chaîne	Huit cas, de text à button	—	Ne lève pas	isDataField() vaut false pour button et 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

Contrat de comportement

• Enveloppe versionnée. Chaque DTO de premier niveau (ExtractedText, DocumentSegmentation, FormData) implémente InteropResultInterface. Sa sortie toArray() porte toujours schema_version ('1.0') et un discriminant type : extracted_text, document_segmentation ou form_data.
• Encodage JSON. toJson() délègue à json_encode avec JSON_THROW_ON_ERROR ajouté par OR aux indicateurs de l’appelant. jsonSerialize() délègue à toArray(), si bien que json_encode($dto) produit la même forme.
• Sérialisation déterministe. L’ordre et la forme des clés sont fixés par le DTO. Segment::toArray() omet la clé children lorsqu’elle est vide ; FormField::toArray() omet bounding_box lorsqu’elle est null. Les consommateurs doivent traiter ces deux clés comme optionnelles.
• Aller-retour. Chaque DTO expose une méthode statique fromArray() qui accepte un objet JSON décodé. Les champs sont protégés en type à cette frontière inter-processus : les valeurs absentes ou mal typées reviennent aux valeurs par défaut documentées au lieu de lever une exception.
• Valeurs de repli des enums. Une chaîne type non reconnue correspond à SegmentType::Unknown dans Segment::fromArray() et à FormFieldType::Text dans FormField::fromArray().
• Coordonnées. Les coordonnées de BoundingBox sont exprimées en unités de l’espace utilisateur PDF (points, 1/72 de pouce), avec l’origine au coin inférieur gauche de la page. Les numéros de page commencent à un partout.
• Jointures en texte brut. ExtractedPage::plainText() joint le contenu des blocs avec des espaces simples. ExtractedText::plainText() joint les pages avec des lignes vides ("\n\n").
• Requêtes de segmentation. ofType(), onPage() et contentSegments() filtrent uniquement les segments de premier niveau et renvoient des listes réindexées. contentSegments() sélectionne les types pour lesquels SegmentType::isContent() vaut true : heading, sub_heading, paragraph, table, list, code.
• Requêtes de formulaire. FormData::dataFields() et toKeyValueMap() excluent les types de champ hors données (button, signature). filledCount() compte les champs dont la valeur est une chaîne non vide.
• Verrou de schéma. SchemaLock::verify() lit le schema.json V1 fourni avec le paquet, normalise les CRLF en LF, calcule le hachage en SHA-256 et le compare à la constante verrouillée en temps constant. La CI l’utilise pour bloquer toute dérive silencieuse du schéma ; la valeur du verrou ne change qu’avec une modification versionnée délibérée du schéma.
• Politique de versionnage. La surface V1 est un contrat public explicite. Les modifications additives incrémentent la version du schéma ; les modifications cassantes exigent une nouvelle version majeure.

Cas limites et modes d’échec

• Le seul membre qui lève une exception sur cette surface est toJson() : JsonException lorsque le tableau n’est pas encodable, par exemple un UTF-8 invalide dans le contenu extrait.
• SchemaLock::verify() renvoie false — ne lève jamais — lorsque le fichier de schéma est absent, illisible ou modifié. Compare expectedHash() et actualHash() pour distinguer une dérive d’un échec d’E/S.
• Les valeurs de repli de fromArray() sont silencieuses par conception. Un page_number mal typé devient 1 ; une confidence mal typée prend la valeur par défaut. Valide en amont lorsque des valeurs par défaut fabriquées sont inacceptables.
• La conversion des chaînes numériques est asymétrique. PageInfo::fromArray() accepte les chaînes numériques pour ses champs int et float ; Segment et TextBlock n’acceptent que int ou float pour confidence et font_size.
• BoundingBox::fromArray() exige les quatre clés conformément à sa forme de tableau documentée. Les DTO qui l’incorporent substituent une boîte nulle (ou null pour FormField) lorsque la clé englobante est absente.
• ExtractedPage::fromArray() substitue un page_info de repli correspondant à la page 1 en 595 × 842 points lorsque la clé est absente ou mal typée.
• FormField::fromArray() n’accepte que des booléens stricts pour required et read_only ; les chaînes et entiers évalués comme vrais correspondent à false.
• Les enfants de Segment récursent sans limite de profondeur. Une imbrication extrêmement profonde n’est bornée que par les limites de mémoire et de pile de PHP.
• Aucune opération de clé cryptographique ou de signature n’a lieu dans ce module. SchemaLock utilise SHA-256 uniquement comme somme de contrôle d’intégrité de fichier ; il n’y a donc aucun comportement spécifique au mode FIPS.

Conformité

Interop V1 est un contrat de transport versionné, propriété de NextPDF. Il n’implémente aucune norme externe, il n’y a donc pas de table de citations normatives. La sémantique de BoundingBox s’aligne sur le modèle de coordonnées de l’espace utilisateur PDF employé par les sous-systèmes Core producteurs ; il s’agit d’une déclaration d’alignement structurel, pas d’un résultat de test de conformité. NextPDF ne détient aucune certification et n’en accorde aucune.

Notes de développement

• Fais un branchement sur schema_version dans les consommateurs. Traite les clés additives comme compatibles ; rejette explicitement les versions majeures inconnues.
• Exécute SchemaLock::verify() en CI. En cas d’échec, journalise expectedHash() et actualHash() et exige une modification versionnée délibérée du schéma, jamais une édition sur place.
• Pour les allers-retours inter-processus, décode avec des tableaux associatifs (json_decode($json, true)) et transmets le résultat au fromArray() correspondant.
• Tous les DTO sont final et readonly. Étends par composition ; dérive de nouvelles vues à partir des champs publics.
• toKeyValueMap() n’aplatit que les champs porteurs de données. Lis les champs signature directement depuis FormData::$fields lorsque leur présence importe.
• La réutilisation est sûre : les DTO ne détiennent aucun état mutable ni aucune ressource ; ils peuvent donc être mis en cache, partagés entre requêtes et sérialisés à répétition.

Périmètre de publication

Cette page documente uniquement le comportement observable de l’extérieur et la surface d’API publique prise en charge. Les chemins de namespace internes, les classes utilitaires, les tables de mécanismes, les noms de fichiers de runbook et les préfixes de ticket sont hors périmètre.

Voir aussi

• Interop — page de capacité
• MCP — Référence détaillée (Pro)
• Extraction — Référence détaillée (Pro)
• Form — Référence détaillée (Pro)