Pro edición

Converter — Referencia detallada

De un vistazo

NextPDF\Pro\Converter exporta un PDF existente a HTML posicionado, SVG simplificado o texto sin formato, y segmenta el contenido del documento en regiones estructurales tipadas. Esta referencia detallada enumera la superficie de la API pública, la matriz de cobertura de operadores, el contrato de comportamiento y los modos de fallo. Es un exportador de extracción de contenido, no un renderizador con precisión de píxeles.

Disponibilidad y licencias

Esta capacidad se incluye en NextPDF Pro (nextpdf/pro) y se activa con un sobre de licencia de nivel Pro. Un despliegue sin esa titularidad 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 del conversor se resuelven siempre que el paquete Pro esté instalado y con licencia.

Superficie de la API pública

Símbolo	Parámetros	Comportamiento predeterminado	Devuelve	Lanza o falla con	Notas
`PdfToHtmlConverter::convert()`	`string $pdfData`, `?ConversionConfig $config = null`	Exporta cada página con texto a un único documento HTML5 autónomo	`ConversionResult` (destino `Html5`)	`InvalidArgumentException` cuando `$pdfData` está vacío	Con config nula, el valor predeterminado es `ConversionTarget::Html5`
`PdfToSvgConverter::convert()`	`string $pdfData`, `int $pageIndex = 0`, `?ConversionConfig $config = null`	Exporta una página a un documento SVG independiente	`ConversionResult` (destino `Svg`; `pageCount` siempre es 1)	`InvalidArgumentException` cuando `$pdfData` está vacío	Un `$pageIndex` fuera de rango produce un SVG solo con fondo
`PdfToTextConverter::convert()`	`string $pdfData`	Extrae el texto decodificado de todas las páginas, separado por un marcador de salto de página	`ConversionResult` (destino `PlainText`)	`InvalidArgumentException` cuando `$pdfData` está vacío	Solo este destino decodifica los escapes de cadenas literales
`PdfToTextConverter::extractPage()`	`string $pdfData`, `int $pageIndex`	Extrae el texto decodificado de una página con índice de base cero	`string`	No lanza; devuelve `''` para una página inexistente o una entrada vacía	A diferencia de `convert()`, no valida la entrada vacía
`DocumentSegmentationEngine::segment()`	`string $pdfData`	Clasifica el contenido de la página en segmentos estructurales tipados mediante heurísticas espaciales y de fuentes	`NextPDF\Pro\Interop\V1\Segment\DocumentSegmentation`	`InvalidArgumentException` cuando la entrada está vacía o no se puede analizar la estructura del PDF	Basado en reglas; no realiza inferencia de IA
`ConversionConfig::__construct()`	`ConversionTarget $target`, `bool $embedFonts = false`, `bool $embedImages = true`, `float $scaleFactor = 1.0`, `string $cssClass = 'pdf-page'`	Ajustes de conversión inmutables	`ConversionConfig`	—	`embedFonts` y `embedImages` se aceptan pero no se utilizan en 3.1.0
`ConversionResult::size()`	—	Longitud en bytes de la salida producida	`int`	—	Campos públicos de solo lectura: `output`, `target`, `pageCount`, `processingTimeMs`
`ConversionResult::isValid()`	—	Indica si la salida no está vacía	`bool`	—	Las estructuras base de documento HTML y SVG nunca están vacías; comprobar `pageCount` en su lugar
`ConversionTarget`	Casos respaldados por cadena `Html5`, `Svg`, `PlainText`	Selecciona el destino de exportación	`mimeType(): string`, `fileExtension(): string`	—	`fileExtension()` corresponde a `html`, `svg`, `txt`

Firmas de los puntos de entrada:

public function convert(string $pdfData, ?ConversionConfig $config = null): ConversionResult

public function convert(
    string $pdfData,
    int $pageIndex = 0,
    ?ConversionConfig $config = null,
): ConversionResult

public function convert(string $pdfData): ConversionResult
public function extractPage(string $pdfData, int $pageIndex): string

public function segment(string $pdfData): DocumentSegmentation

Contrato de comportamiento

Las entradas son bytes de PDF sin procesar; las salidas son un objeto de valor ConversionResult. Los tres conversores de exportación comparten un modelo de escaneo: localizar los límites stream/endstream, aislar los bloques de texto BT/ET y analizar los operadores de mostrado de texto. No analizan la tabla de referencias cruzadas ni descomprimen los flujos comprimidos. DocumentSegmentationEngine se distingue: resuelve el tráiler, el catálogo y el árbol de páginas, y descomprime el contenido de página FlateDecode antes de la clasificación.

Cobertura de operadores:

Operador PDF	HTML	SVG	Texto
`Tj` (mostrar cadena)	sí	sí	sí
`TJ` (mostrar arreglo)	sí	sí	sí
`'` (mover + mostrar)	no	no	sí
`Td` / `Tm` (posición)	sí	sí	n/d
`Tf` (tamaño de fuente)	sí	sí	n/d
`re` (rectángulo)	no	sí	no
`m` / `l` (línea)	no	sí	no
`RG` (trazo RGB)	no	sí (aplicado al trazo de rectángulos/líneas)	no
curvas, sombreado, recorte, imágenes	no	no	no

Posicionamiento. Cada bloque BT/ET resuelve una posición a partir de su primera coincidencia Td o Tm; Tm tiene prioridad cuando aparecen ambos. El eje Y se invierte del espacio de usuario del PDF al espacio de salida con origen en la esquina superior izquierda. El tamaño de fuente es de 12 pt de forma predeterminada cuando no hay ningún Tf.
Geometría de página. HTML y SVG asumen un cuadro de página A4 (595 x 842 pt) multiplicado por scaleFactor. La raíz del SVG lleva atributos viewBox, width y height coincidentes sobre un rectángulo de fondo blanco.
Color de trazo. Los operadores RG se resuelven posicionalmente, de modo que un flujo que cambia el color de trazo más de una vez colorea cada rectángulo y línea según el operador precedente más reciente. Los componentes se ajustan al rango 0..1 antes de la conversión a hexadecimal. El relleno de los rectángulos siempre es negro; el operador de relleno rg no se evalúa.
Decodificación de cadenas. El destino de texto decodifica los escapes de cadenas literales según ISO 32000-2:2020 §7.3.4.2: escapes con nombre, códigos octales \ddd enmascarados a un byte, continuaciones de línea con barra invertida y eliminación de barras invertidas sueltas. Los destinos HTML y SVG emiten los bytes sin procesar entre paréntesis tras el escapado HTML o XML; no decodifican los escapes.
Ensamblaje de la salida. El destino de texto une los textos de los bloques con un espacio y las páginas con --- Page Break --- enmarcado por líneas en blanco. El destino HTML emite un <div> posicionado de forma absoluta por cada bloque de texto dentro de un contenedor por página que lleva la clase CSS configurada y un atributo data-page.
Determinismo. Para una entrada y configuración idénticas, los bytes HTML, SVG o de texto producidos son estables. processingTimeMs es una medición de tiempo real y queda excluido de la superficie determinista.

Casos límite y modos de fallo

Entrada vacía: cada punto de entrada convert() y segment() lanza InvalidArgumentException («PDF data must not be empty»). No se produce ninguna salida parcial. extractPage() es la excepción: devuelve '' sin lanzar.
Los flujos sin BT/ET son omitidos por los conversores HTML y de texto. Un PDF que contiene solo ese tipo de flujos produce un pageCount de cero con una salida de texto vacía o una estructura base HTML sin páginas.
isValid() solo comprueba que la salida no esté vacía. Los conversores HTML y SVG siempre emiten una estructura base de documento, por lo que isValid() permanece true incluso cuando no se encontró texto; usar pageCount (HTML, texto) para detectar una extracción vacía.
El contenido FlateDecode no es descomprimido por los tres conversores de exportación. Los PDF exclusivamente comprimidos exportan poco o ningún contenido a través de ellos. segment() sí descomprime los flujos de página FlateDecode.
segment() limita la descompresión por tamaño de cada flujo, ratio de compresión y un presupuesto acumulado. Un flujo que supera un límite degrada a contenido de página vacío en lugar de agotar la memoria; no lanza.
segment() lanza InvalidArgumentException cuando no se puede resolver el tráiler, el desplazamiento de referencias cruzadas, el catálogo del documento o el árbol de páginas.
La indexación de páginas difiere según el conversor. Los conversores HTML y de texto cuentan solo los flujos con texto; el conversor SVG cuenta los flujos que contienen cualquier operador de gráficos o de texto reconocido. Por lo tanto, el mismo $pageIndex puede referirse a flujos diferentes.
Los ajustes numéricos de interletraje de TJ se descartan; las cadenas del arreglo se concatenan sin espaciado entre glifos.
No se aplica la asignación de glifos a Unicode. El texto compuesto con fuentes de codificaciones personalizadas se exporta como la secuencia de bytes sin procesar.
El texto rotado, las transformaciones no textuales y el flujo en columnas se aproximan mediante el posicionamiento por primera coincidencia y podrían no reproducir el diseño original.
No se realiza ninguna operación criptográfica en este módulo, por lo que el modo FIPS no tiene ningún comportamiento específico del módulo.

Conformidad

NextPDF documenta la capacidad frente a las cláusulas citadas. Las declaraciones de compatibilidad describen el comportamiento implementado; no son resultados de pruebas de conformidad ni certificaciones, y NextPDF no posee ninguna certificación.

Afirmación	Cláusula de la especificación	Estado
Operador de mostrado de texto `Tj` analizado	ISO 32000-2:2020 §9.4	Verificado (conjunto de pruebas unitarias)
Operador de mostrado de texto en arreglo `TJ` analizado	ISO 32000-2:2020 §9.4	Verificado (conjunto de pruebas unitarias)
Operador de mover-y-mostrar `'` analizado (solo destino de texto)	ISO 32000-2:2020 §9.4	Verificado (conjunto de pruebas unitarias)
Escapes de cadenas literales decodificados (solo destino de texto)	ISO 32000-2:2020 §7.3.4.2	Implementado; los bytes se devuelven tal cual, la interpretación del juego de caracteres es posterior
Construcción de trazados `re`, `m`, `l` reconocida (destino SVG)	ISO 32000-2:2020 §8.5.2	Parcial: subconjunto sin evaluación de curvas, cierre ni modo de pintado
Máquina de estado de texto completa y renderizado de página	—	No compatible (fuera de alcance)

El conversor analiza los operadores de mostrado de texto para recuperar el contenido; no implementa la máquina de estado de texto completa, por lo que el posicionamiento de glifos es aproximado en lugar de exacto según la especificación.

Notas de desarrollo

El análisis es lineal respecto a la longitud en bytes del PDF. La memoria sigue a la entrada más la cadena de salida producida. El campo performance_budget del front matter es la referencia por invocación para un documento de oficina típico.
Los conversores analizan bytes de PDF no confiables con un escaneo acotado mediante strpos/substr. No ejecutan ningún JavaScript incrustado ni siguen referencias externas. Tratar el HTML exportado como contenido no confiable y escaparlo para su destino.
La salida HTML se escapa con htmlspecialchars (ENT_QUOTES, HTML5); el texto SVG se escapa como XML. La cssClass configurada se escapa antes de la emisión.
Consumo de la configuración: scaleFactor se aplica a los destinos HTML y SVG; cssClass se aplica solo a HTML; embedFonts y embedImages están reservados y actualmente no se usan; el campo target no anula el propio formato de salida de un conversor.
Los conversores de exportación se incluyen desde la 1.9.0; DocumentSegmentationEngine se incluye desde la 2.1.0 y respalda la herramienta MCP segment_document de Pro y el contrato de segmentación de Interop.
PdfPageExtractor y PdfPageData en el mismo espacio de nombres son internos del motor de segmentación y no forman parte de la API pública.

Límite de publicación

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