Converter

De un vistazo

NextPDF\Pro\Converter lee un PDF existente y exporta su contenido a uno de tres destinos basados en texto: HTML posicionado, SVG simplificado o texto sin formato. Es un exportador de extracción de contenido, no un renderizador de PDF con fidelidad de píxel.

Disponibilidad y licencia

Esta capacidad se incluye en NextPDF Pro (nextpdf/pro) y se activa con un envoltorio de licencia de nivel Pro. Un despliegue sin ese derecho no carga las clases de la capacidad. Compare ediciones y obtenga una licencia.

Ningún indicador de capacidad en tiempo de ejecución restringe este módulo. Las clases de Converter se resuelven siempre que el paquete Pro esté instalado y cargado automáticamente.

Instalación

composer require nextpdf/pro:^3

Descripción conceptual

El Converter analiza los operadores de presentación de texto dentro de un flujo de contenido PDF — Tj, TJ y ' conforme a ISO 32000-2:2020 §9.4— y reconstruye una representación aproximada de cada página. Lee la posición a partir de los operadores de texto Td y Tm y el tamaño de fuente a partir de Tf, y luego asigna los puntos a coordenadas de salida.

Se exponen tres conversores, uno por ConversionTarget:

• PdfToHtmlConverter envuelve cada página en un contenedor posicionado y emite elementos <div> posicionados de forma absoluta para cada serie de texto. La salida es un documento HTML5 autónomo.
• PdfToSvgConverter analiza un conjunto limitado de operadores de dibujo (rectángulos mediante re, líneas mediante m/l) además del texto, y emite los elementos <rect>, <line> y <text> correspondientes para una página.
• PdfToTextConverter extrae únicamente el texto decodificado, página por página, separado por un marcador de salto de página.

Es un exportador deliberadamente acotado. Aproxima la posición del texto; no hace reflujo, no rasteriza y no reproduce trazados vectoriales, sombreados, recortes, transparencia ni imágenes incrustadas. Para el renderizado de HTML a PDF con fidelidad completa en la dirección opuesta, use el pipeline HTML de Core.

Por qué funciona así

Un PDF almacena el texto como operadores de presentación de glifos posicionados, no como caracteres semánticos, por lo que no hay ningún texto de documento fiable que leer de vuelta. Por eso el Converter escanea directamente los operadores del flujo de contenido —Tj, TJ, ', además de Td, Tm y Tf para la ubicación— y reconstruye una maquetación aproximada en lugar de hacer reflujo o rasterizar la página. Ese escaneo acotado es lo que mantiene la exportación lineal respecto a la longitud en bytes, determinista para una entrada idéntica y segura ante bytes no confiables sin ejecutar lógica incrustada. También establece el techo honesto: los glifos no se reasignan de forma inversa a Unicode, por lo que las fuentes con codificación personalizada se exportan como bytes en bruto y la fidelidad visual exacta queda fuera del alcance. Contexto de diseño: Por qué el texto de un PDF no es realmente texto.

Contrato de comportamiento

• Entrada. Bytes de PDF en bruto (string). Una cadena vacía genera InvalidArgumentException.
• Salida. Un objeto de valor ConversionResult que contiene la cadena producida, el ConversionTarget, el número de páginas procesadas y una medición del tiempo de procesamiento.
• Cobertura. La exportación de texto (Tj/TJ/') es la ruta verificada, ejercitada por el conjunto unitario. La exportación de SVG cubre rectángulos, líneas rectas y texto únicamente. El color de trazo RGB aún no se propaga a la salida SVG.
• Determinismo. Para una entrada y configuración idénticas, el flujo de bytes HTML, SVG o de texto producido es estable. El campo processingTimeMs es una medición de tiempo de pared y no forma parte de la superficie determinista.
• Codificación. La salida HTML está escapada con htmlspecialchars; la salida SVG está escapada como XML. Las secuencias de escape de cadena PDF habituales (\n, \r, \t, \(, \), \\) se decodifican para el destino de texto.

Superficie pública de la API

Tipo	Categoría	Miembros clave
NextPDF\Pro\Converter\PdfToHtmlConverter	final class	convert(string $pdfData, ?ConversionConfig $config = null): ConversionResult
NextPDF\Pro\Converter\PdfToSvgConverter	final class	convert(string $pdfData, int $pageIndex = 0, ?ConversionConfig $config = null): ConversionResult
NextPDF\Pro\Converter\PdfToTextConverter	final class	convert(string $pdfData): ConversionResult, extractPage(string $pdfData, int $pageIndex): string
NextPDF\Pro\Converter\ConversionConfig	final readonly class	__construct(ConversionTarget $target, bool $embedFonts = false, bool $embedImages = true, float $scaleFactor = 1.0, string $cssClass = 'pdf-page')
NextPDF\Pro\Converter\ConversionResult	final readonly class	string $output, ConversionTarget $target, int $pageCount, float $processingTimeMs, size(): int, isValid(): bool
NextPDF\Pro\Converter\ConversionTarget	enum	Html5, Svg, PlainText; mimeType(): string, fileExtension(): string

Ejemplo de código — Inicio rápido

<?php

declare(strict_types=1);

use NextPDF\Pro\Converter\PdfToTextConverter;

$pdf    = file_get_contents('report.pdf');
$result = (new PdfToTextConverter())->convert($pdf);

echo $result->pageCount, " pages, ", $result->size(), " bytes of text\n";
echo $result->output;

Ejemplo de código — Producción

<?php

declare(strict_types=1);

use NextPDF\Pro\Converter\ConversionConfig;
use NextPDF\Pro\Converter\ConversionTarget;
use NextPDF\Pro\Converter\PdfToHtmlConverter;

function exportPreview(string $pdfBytes): string
{
    if ($pdfBytes === '') {
        throw new InvalidArgumentException('empty PDF payload');
    }

    $config = new ConversionConfig(
        target: ConversionTarget::Html5,
        scaleFactor: 1.0,
        cssClass: 'doc-preview',
    );

    $result = (new PdfToHtmlConverter())->convert($pdfBytes, $config);

    if (! $result->isValid()) {
        throw new RuntimeException('converter produced no output');
    }

    return $result->output;
}

Casos límite y trampas

• Un PDF sin bloques de texto BT/ET produce una salida vacía o solo con la estructura de página; los PDF escaneados (que solo contienen imágenes) no producen texto porque no hay paso de OCR.
• PdfToSvgConverter convierte una sola página a la vez, seleccionada mediante $pageIndex; un índice fuera de rango produce un flujo de página vacío.
• La posición es aproximada. El texto colocado con transformaciones no textuales, el texto rotado o el flujo en columnas pueden no reproducir su maquetación visual original.
• No se aplica la asignación de glifo a Unicode; el texto de fuentes que usan codificaciones personalizadas puede exportarse como la secuencia de bytes en bruto.

Rendimiento

El análisis es lineal respecto a la longitud en bytes del PDF. La memoria sigue la entrada más la cadena de salida producida. El front-matter performance_budget es la referencia por invocación para un documento de oficina típico.

Notas de seguridad

El conversor analiza bytes de PDF no confiables con un escaneo acotado de strpos/substr sobre los operadores de texto; no ejecuta JavaScript incrustado ni sigue referencias externas. Trate el HTML exportado como contenido no confiable y escápelo de forma apropiada para su destino. Consulte el modelo de seguridad de Core.

Conformidad

Declaración	Cláusula del estándar	Estado
Operador de presentación de texto Tj analizado	ISO 32000-2:2020 §9.4	Verificado (conjunto unitario)
Operador de presentación de texto en array TJ analizado	ISO 32000-2:2020 §9.4	Verificado (conjunto unitario)
Fidelidad de página vectorial/ráster completa	—	No admitido (fuera del alcance)

Alternativa / respaldo de Core

No existe ningún equivalente en Core para la exportación de PDF. Para la dirección directa (crear un PDF a partir de HTML), el pipeline HTML de Core de código abierto es la ruta admitida. Consulte /modules/core/html/.

Nota sobre el límite de Enterprise

El Converter es un exportador de texto/formas de nivel Pro. No realiza OCR, reconstrucción semántica ni comprensión de documentos. Esas son cuestiones separadas y no las proporciona este módulo.

Límite de publicación

Esta página documenta únicamente el comportamiento observable externamente y la superficie pública admitida de la API. Las rutas de espacios de nombres internos, 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

• Converter — Referencia detallada
• Extraction
• Diff
• Pipeline HTML de Core