Interop — Referencia detallada

De un vistazo

Esta página es la referencia a nivel de contrato de NextPDF\Pro\Interop\V1. El módulo contiene catorce símbolos públicos: un contrato de serialización (InteropResultInterface), una guarda de integridad para CI (SchemaLock), tres DTO de resultado de nivel superior (ExtractedText, DocumentSegmentation, FormData) y nueve objetos de valor y enumeraciones de apoyo. Cada DTO es una vista inmutable y serializable a JSON de un resultado de análisis. La forma del formato de transmisión está versionada y bloqueada; nada en esta superficie vuelve a ejecutar el análisis. La vista orientada a tareas reside en la página de capacidad.

Disponibilidad y licencias

Esta capacidad se distribuye en NextPDF Pro (nextpdf/pro) y se activa con un envoltorio de licencia de nivel Pro. Un despliegue sin esa habilitación no carga las clases de la capacidad. Comparar ediciones y obtener una licencia.

Ningún indicador de capacidad en tiempo de ejecución restringe este módulo. Las clases están disponibles siempre que nextpdf/pro esté instalado y licenciado.

Superficie pública de la API

Símbolo	Parámetros	Comportamiento por defecto	Devuelve	Lanza o falla con	Notas
InteropResultInterface	—	Contrato para los DTO de resultado de nivel superior; extiende JsonSerializable	—	No lanza	SCHEMA_VERSION es la cadena '1.0'.
InteropResultInterface::toArray()	ninguno	Serializa a un array seguro para JSON que siempre incluye schema_version	array<string, mixed>	No lanza	Las implementaciones también emiten un discriminador type.
InteropResultInterface::toJson()	int $flags = 0	Codifica la salida de toArray(); JSON_THROW_ON_ERROR siempre se agrega con OR	string	JsonException con datos no codificables	Pase indicadores como JSON_PRETTY_PRINT.
SchemaLock::verify()	ninguno	Aplica hash al schema.json V1 en disco y lo compara con el SHA-256 bloqueado	bool	No lanza	false cuando el archivo de esquema falta, es ilegible o ha sido modificado.
SchemaLock::expectedHash()	ninguno	Devuelve el hash bloqueado	string	No lanza	Salida de diagnóstico para el triaje de fallos en CI.
SchemaLock::actualHash()	ninguno	Devuelve el hash del archivo de esquema actual	string	No lanza	Las cadenas centinela FILE_NOT_FOUND / READ_FAILED reemplazan al hash ante un fallo de E/S.
BoundingBox	float $x, float $y, float $width, float $height	Caja inmutable en puntos del espacio de usuario del PDF, con origen en la esquina inferior izquierda	—	No lanza	area(), overlaps(), toArray(), fromArray().
DocumentInfo	int $pageCount más seis campos de metadatos opcionales	Metadatos inmutables del documento	—	No lanza	fromArray() aplica guardas de tipo a cada campo; los campos ausentes recurren a valores por defecto.
PageInfo	int $pageNumber, float $width, float $height, int $rotation = 0	Metadatos inmutables de la página	—	No lanza	isLandscape(); fromArray() coacciona cadenas numéricas y floats.
ExtractedText	list<ExtractedPage> $pages, DocumentInfo $documentInfo, float $processingTimeMs = 0.0	Resultado de extracción de texto de todo el documento	—	JsonException solo desde toJson()	page(), totalBlockCount(), plainText(), fromArray().
ExtractedPage	PageInfo $pageInfo, list<TextBlock> $textBlocks	Contenedor por página de bloques de texto en orden de lectura	—	No lanza	plainText() une el contenido de los bloques con espacios simples.
TextBlock	string $content, BoundingBox $boundingBox, int $pageNumber, string $fontName = '', float $fontSize = 0.0	Ejecución de texto contiguo y posicionado	—	No lanza	El nombre y el tamaño de la fuente son de mejor esfuerzo (fuente dominante del bloque).
DocumentSegmentation	list<Segment> $segments, DocumentInfo $documentInfo, float $processingTimeMs = 0.0	Resultado de segmentación con reconocimiento del diseño	—	JsonException solo desde toJson()	segmentCount(), ofType(), onPage(), contentSegments(), fromArray().
Segment	SegmentType $type, string $content, BoundingBox $boundingBox, int $pageNumber, float $confidence = 1.0, list<Segment> $children = []	Región de página clasificada; los hijos se anidan de forma recursiva	—	No lanza	El umbral de isHighConfidence() es 0.8; descendantCount() es recursivo.
SegmentType	enumeración respaldada por cadena	Doce casos, de heading a unknown	—	No lanza	isContent() e isStructural() particionan los casos.
FormData	list<FormField> $fields, DocumentInfo $documentInfo, float $processingTimeMs = 0.0	Resultado de extracción de formularios de todo el documento	—	JsonException solo desde toJson()	field(), dataFields(), filledCount(), toKeyValueMap(), fromArray().
FormField	string $name, FormFieldType $type, más seis campos opcionales	Un único campo de formulario extraído	—	No lanza	isFilled() es value !== ''.
FormFieldType	enumeración respaldada por cadena	Ocho casos, de text a button	—	No lanza	isDataField() es false para button y 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

Contrato de comportamiento

• Envoltorio versionado. Cada DTO de nivel superior (ExtractedText, DocumentSegmentation, FormData) implementa InteropResultInterface. Su salida de toArray() siempre incluye schema_version ('1.0') y un discriminador type: extracted_text, document_segmentation o form_data.
• Codificación JSON. toJson() delega en json_encode con JSON_THROW_ON_ERROR agregado con OR a los indicadores del llamador. jsonSerialize() delega en toArray(), de modo que json_encode($dto) produce la misma forma.
• Serialización determinista. El orden y la forma de las claves están fijados por el DTO. Segment::toArray() omite la clave children cuando está vacía; FormField::toArray() omite bounding_box cuando es null. Los consumidores deben tratar ambas claves como opcionales.
• Ida y vuelta. Cada DTO expone un fromArray() estático que acepta un objeto JSON decodificado. Los campos reciben guardas de tipo en este límite entre procesos: los valores ausentes o con tipo incorrecto recurren a los valores por defecto documentados en lugar de lanzar una excepción.
• Valores de reserva de las enumeraciones. Una cadena type no reconocida se asigna a SegmentType::Unknown en Segment::fromArray() y a FormFieldType::Text en FormField::fromArray().
• Coordenadas. Las coordenadas de BoundingBox son unidades del espacio de usuario del PDF (puntos, 1/72 de pulgada) con el origen en la esquina inferior izquierda de la página. Los números de página son de base uno en toda la superficie.
• Uniones de texto plano. ExtractedPage::plainText() une el contenido de los bloques con espacios simples. ExtractedText::plainText() une las páginas con líneas en blanco ("\n\n").
• Consultas de segmentación. ofType(), onPage() y contentSegments() filtran solo los segmentos de nivel superior y devuelven listas reindexadas. contentSegments() selecciona los tipos donde SegmentType::isContent() es true: heading, sub_heading, paragraph, table, list, code.
• Consultas de formulario. FormData::dataFields() y toKeyValueMap() excluyen los tipos de campo que no son de datos (button, signature). filledCount() cuenta los campos cuyo valor es una cadena no vacía.
• Bloqueo de esquema. SchemaLock::verify() lee el schema.json V1 distribuido con el paquete, normaliza CRLF a LF, aplica hash con SHA-256 y compara con la constante bloqueada en tiempo constante. CI lo usa para bloquear una deriva silenciosa del esquema; el valor del bloqueo cambia solo con un cambio de esquema versionado y deliberado.
• Política de versionado. La superficie V1 es un contrato público explícito. Los cambios aditivos incrementan la versión del esquema; los cambios incompatibles requieren una nueva versión mayor.

Casos límite y modos de fallo

• El único miembro que lanza en esta superficie es toJson(): JsonException cuando el array no es codificable, por ejemplo con UTF-8 inválido en el contenido extraído.
• SchemaLock::verify() devuelve false —nunca lanza— cuando el archivo de esquema falta, es ilegible o ha sido modificado. Compare expectedHash() con actualHash() para distinguir la deriva de un fallo de E/S.
• Los valores de reserva de fromArray() son silenciosos por diseño. Un page_number con tipo incorrecto se convierte en 1; un confidence con tipo incorrecto se convierte en el valor por defecto. Valide aguas arriba cuando los valores por defecto fabricados sean inaceptables.
• La coacción de cadenas numéricas es asimétrica. PageInfo::fromArray() acepta cadenas numéricas para sus campos int y float; Segment y TextBlock aceptan solo int o float para confidence y font_size.
• BoundingBox::fromArray() requiere las cuatro claves según su forma de array documentada. Los DTO que la incorporan sustituyen una caja cero (o null para FormField) cuando la clave envolvente está ausente.
• ExtractedPage::fromArray() sustituye un page_info de reserva de la página 1 a 595 × 842 puntos cuando la clave falta o tiene un tipo incorrecto.
• FormField::fromArray() acepta solo booleanos estrictos para required y read_only; las cadenas y los enteros con valor de verdad se asignan a false.
• Los hijos de Segment recurren sin límite de profundidad. Un anidamiento extremadamente profundo está acotado únicamente por los límites de memoria y pila de PHP.
• En este módulo no ocurre ninguna operación con clave criptográfica ni con firma. SchemaLock usa SHA-256 únicamente como suma de comprobación de integridad de archivo, por lo que no hay comportamiento específico del modo FIPS.

Conformidad

Interop V1 es un contrato de formato de transmisión versionado y propiedad de NextPDF. No implementa un estándar externo, por lo que no hay tabla de citas normativas. La semántica de BoundingBox se alinea con el modelo de coordenadas del espacio de usuario del PDF que usan los subsistemas de Core productores; esto es una declaración de alineación estructural, no un resultado de prueba de conformidad. NextPDF no posee ninguna certificación ni la otorga.

Notas de desarrollo

• Ramifique según schema_version en los consumidores. Trate las claves aditivas como compatibles; rechace explícitamente las versiones mayores desconocidas.
• Ejecute SchemaLock::verify() en CI. Ante un fallo, registre expectedHash() y actualHash() y exija un cambio de esquema versionado y deliberado, nunca una edición en el sitio.
• Para las idas y vueltas entre procesos, decodifique con arrays asociativos (json_decode($json, true)) y alimente el resultado al fromArray() correspondiente.
• Todos los DTO son final y readonly. Extienda mediante composición; derive nuevas vistas a partir de los campos públicos.
• toKeyValueMap() aplana solo los campos portadores de datos. Lea los campos signature directamente desde FormData::$fields cuando su presencia importe.
• La reutilización es segura: los DTO no mantienen estado mutable ni recursos, por lo que pueden almacenarse en caché, compartirse entre solicitudes y serializarse repetidamente.

Límite de publicación

Esta página documenta únicamente el comportamiento observable externamente y la superficie pública de API compatible. Las rutas de espacio de nombres internas, las clases auxiliares, las tablas de mecanismos, los nombres de archivo de los runbooks y los prefijos de tickets quedan fuera del alcance.

Véase también

• Interop — página de capacidad
• MCP — Referencia detallada (Pro)
• Extracción — Referencia detallada (Pro)
• Formularios — Referencia detallada (Pro)