Interop

De un vistazo

NextPDF Pro proporciona un conjunto versionado de objetos de transferencia de datos (DTO) de resultado que serializan la salida del análisis de PDF —información del documento, páginas, bloques de texto, segmentación y datos de formulario— a una forma JSON estable y bloqueada por esquema, para su consumo por sistemas y herramientas externos.

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. Interop forma parte de la edición Pro; no existe un indicador de licencia independiente por función. Compare ediciones y obtenga una licencia.

Instalación

composer require nextpdf/pro:^3

Descripción conceptual

Cuando la salida del procesamiento de PDF cruza un límite de proceso o de servicio, el receptor necesita un contrato estable. La superficie Interop V1 lo proporciona:

• InteropResultInterface — todos los DTO de resultado la implementan. Cada uno se serializa a un array seguro para JSON que siempre lleva una clave schema_version, y a una cadena JSON.
• DTO de resultado — DocumentInfo, PageInfo, BoundingBox, ExtractedText / ExtractedPage / TextBlock, DocumentSegmentation / Segment y FormData / FormField. Cada uno es una vista inmutable de un resultado de análisis.
• SchemaLock — una protección de CI. Mantiene el SHA-256 del esquema congelado y hace fallar la compilación si el archivo de esquema cambia sin un incremento de versión correspondiente, de modo que el contrato de cable no pueda derivar de forma silenciosa.

La superficie Interop está versionada de forma explícita (SCHEMA_VERSION). Trátela como un contrato de API pública: los cambios aditivos incrementan el esquema; los cambios incompatibles requieren una nueva versión mayor.

Por qué funciona así

La forma de serialización se trata como un contrato de API pública, no como un detalle de implementación. Todos los DTO llevan una clave schema_version, de modo que los consumidores ramifican según la forma que reciben en lugar de adivinarla. SchemaLock fija el SHA-256 del esquema congelado en CI, de modo que el formato no puede derivar sin un incremento de versión. Eso es lo que permite a los sistemas externos construir sobre el JSON con seguridad: el contrato solo se mueve cuando lo hace la versión. La salida se mantiene portátil —datos documentados, versionados y de su propiedad, no una forma que cambia bajo sus pies—.

Contexto de diseño: Núcleo abierto, sin dependencia forzada.

Superficie de la API

Clase	Responsabilidad
InteropResultInterface	Contrato de serialización común.
DocumentInfo, PageInfo, BoundingBox	DTO comunes de documento/página.
ExtractedText, ExtractedPage, TextBlock	DTO de extracción de texto.
DocumentSegmentation, Segment	DTO de segmentación de documentos.
FormData, FormField	DTO de datos de formulario.
SchemaLock	Protección de CI contra la deriva del esquema.

Ejemplo de código — Inicio rápido

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

Ejemplo de código — Producción

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

Casos límite y trampas

• toArray() siempre incluye schema_version; los consumidores aguas abajo deben ramificar según él.
• SchemaLock::verify() devuelve false si el archivo de esquema falta o ha sido modificado.
• Los DTO son vistas de solo lectura; no vuelven a ejecutar el análisis.

Rendimiento

La serialización es lineal respecto al tamaño del grafo de resultado.

Notas de seguridad

Los DTO transportan únicamente la salida de análisis que usted rellena. No se produce ninguna E/S de sistema de archivos ni de red durante la serialización.

Conformidad

Interop define un esquema versionado propio de NextPDF; no implementa ningún estándar externo.

Contrato de comportamiento

• Todos los DTO de resultado implementan InteropResultInterface y se serializan a un array seguro para JSON que siempre lleva una clave schema_version, y a una cadena JSON.
• Los DTO de resultado (DocumentInfo, PageInfo, BoundingBox, ExtractedText/ExtractedPage/TextBlock, DocumentSegmentation/Segment, FormData/FormField) son vistas inmutables de solo lectura; no vuelven a ejecutar el análisis.
• SchemaLock::verify() mantiene el SHA-256 del esquema congelado y devuelve false si el archivo de esquema falta o ha sido modificado, de modo que el contrato de cable no pueda derivar de forma silenciosa.
• La superficie está versionada de forma explícita (SCHEMA_VERSION): los cambios aditivos incrementan el esquema; los cambios incompatibles requieren una nueva versión mayor.
• No se produce ninguna E/S de sistema de archivos ni de red durante la serialización.

Nota sobre el límite de Enterprise

Enterprise no cambia el comportamiento de Interop. Enterprise añade funciones de nivel superior documentadas por separado; no son necesarias para usar los DTO de resultado versionados.

Alternativa / respaldo de Core

No existe ningún equivalente en Core para los DTO de resultado versionados y bloqueados por esquema. Es una adición de Pro.

Límite de publicación

Esta página documenta únicamente el comportamiento observable externamente y la superficie pública de la API admitida. Las rutas de espacios de nombres internos, las clases auxiliares, las tablas de mecanismos, los nombres de archivo de runbook y los prefijos de ticket quedan fuera de alcance.

Véase también

• Extraction — produce resultados de texto y de segmentos.
• Form — produce resultados de datos de formulario.
• Interop — Referencia profunda — referencia completa de campos de los DTO.