Conversor

Visão geral

NextPDF\Pro\Converter lê um PDF existente e exporta seu conteúdo para um de três alvos baseados em texto: HTML posicionado, SVG simplificado ou texto simples. É um exportador de extração de conteúdo, não um renderizador de PDF com fidelidade de pixel.

Disponibilidade e licenciamento

Este recurso é entregue no NextPDF Pro (nextpdf/pro) e é ativado com um envelope de licença de nível Pro. Uma implantação sem esse direito não carrega as classes do recurso. Compare as edições e obtenha uma licença.

Nenhum sinalizador de capacidade em tempo de execução restringe este módulo. As classes do Converter são resolvidas sempre que o pacote Pro está instalado e com autoload.

Instalação

composer require nextpdf/pro:^3

Visão conceitual

O Converter analisa os operadores de exibição de texto dentro de um stream de conteúdo PDF — Tj, TJ e ' conforme a ISO 32000-2:2020 §9.4 — e reconstrói uma representação aproximada de cada página. Ele lê o posicionamento dos operadores de texto Td e Tm e o tamanho da fonte de Tf, depois mapeia pontos para coordenadas de saída.

Três conversores são expostos, um por ConversionTarget:

• PdfToHtmlConverter envolve cada página em um contêiner posicionado e emite elementos <div> posicionados de forma absoluta para cada trecho de texto. A saída é um documento HTML5 autocontido.
• PdfToSvgConverter analisa um conjunto limitado de operadores de desenho (retângulos via re, linhas via m/l) mais texto, e emite os elementos <rect>, <line> e <text> correspondentes para uma página.
• PdfToTextConverter extrai apenas o texto decodificado, página por página, separado por um marcador de quebra de página.

Este é um exportador deliberadamente limitado. Ele aproxima a posição do texto; ele não faz reflow, não rasteriza e não reproduz caminhos vetoriais, sombreamento, recorte, transparência ou imagens incorporadas. Para renderização HTML-para-PDF com fidelidade total na direção oposta, use o pipeline HTML do Core.

Por que funciona assim

Um PDF armazena texto como operadores posicionados de exibição de glifos, não como caracteres semânticos, então não há texto de documento confiável para ler de volta. Portanto, o Converter varre os operadores do stream de conteúdo diretamente — Tj, TJ, ', mais Td, Tm e Tf para posicionamento — e reconstrói um layout aproximado em vez de fazer reflow ou rasterizar a página. Essa varredura limitada é o que mantém a exportação linear no comprimento em bytes, determinística para entradas idênticas e segura sobre bytes não confiáveis sem executar lógica incorporada. Isso também define o teto honesto: os glifos não são mapeados de volta para Unicode, então fontes com codificação personalizada são exportadas como bytes brutos e a fidelidade visual exata fica fora de escopo. Contexto de design: Por que o texto em um PDF não é realmente texto.

Contrato de comportamento

• Entrada. Bytes brutos do PDF (string). Uma string vazia gera InvalidArgumentException.
• Saída. Um objeto de valor ConversionResult contendo a string produzida, o ConversionTarget, a contagem de páginas processadas e uma medição de tempo de processamento.
• Cobertura. A exportação de texto (Tj/TJ/') é o caminho verificado, exercitado pelo conjunto de testes unitários. A exportação de SVG cobre apenas retângulos, linhas retas e texto. A cor de traço RGB ainda não é propagada para a saída SVG.
• Determinismo. Para entradas e configurações idênticas, o stream de bytes HTML, SVG ou texto produzido é estável. O campo processingTimeMs é uma medição de tempo de parede e não faz parte da superfície determinística.
• Codificação. A saída HTML é escapada com htmlspecialchars; a saída SVG é escapada como XML. Sequências de escape comuns de strings PDF (\n, \r, \t, \(, \), \\) são decodificadas para o alvo de texto.

Superfície pública da API

Tipo	Categoria	Membros principais
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

Exemplo de código — Início 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;

Exemplo de código — Produção

<?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 extremos e armadilhas

• Um PDF sem blocos de texto BT/ET gera saída vazia ou apenas com o invólucro da página; PDFs digitalizados (apenas com imagens) não produzem texto porque não há etapa de OCR.
• PdfToSvgConverter converte uma única página por vez, selecionada por $pageIndex; um índice fora do intervalo gera um stream de página vazio.
• O posicionamento é aproximado. Texto posicionado com transformações que não são de texto, texto rotacionado ou fluxo em colunas pode não reproduzir seu layout visual original.
• O mapeamento de glifo para Unicode não é aplicado; texto de fontes que usam codificações personalizadas pode ser exportado como a sequência de bytes bruta.

Desempenho

A análise é linear no comprimento em bytes do PDF. A memória acompanha a entrada mais a string de saída produzida. O front-matter performance_budget é a referência por invocação para um documento de escritório típico.

Notas de segurança

O conversor analisa bytes de PDF não confiáveis com varredura limitada por strpos/substr sobre os operadores de texto; ele não executa JavaScript incorporado nem segue referências externas. Trate o HTML exportado como conteúdo não confiável e escape-o adequadamente para seu destino. Consulte o modelo de segurança do Core.

Conformidade

Alegação	Cláusula da spec	Status
Operador de exibição de texto Tj analisado	ISO 32000-2:2020 §9.4	Verificado (conjunto de testes unitários)
Operador de exibição de texto em array TJ analisado	ISO 32000-2:2020 §9.4	Verificado (conjunto de testes unitários)
Fidelidade total de página vetorial/raster	—	Não suportado (fora de escopo)

Alternativa / fallback do Core

Não há equivalente no Core para exportação de PDF. Para a direção direta (criar um PDF a partir de HTML), o pipeline HTML do Core open-source é o caminho suportado. Consulte /modules/core/html/.

Nota sobre o limite do Enterprise

O Converter é um exportador de texto/formas de nível Pro. Ele não realiza OCR, reconstrução semântica ou compreensão de documentos. Essas são preocupações separadas e não são fornecidas por este módulo.

Limite de publicação

Esta página documenta apenas o comportamento observável externamente e a superfície pública suportada da API. Caminhos de namespace interno, classes helper, tabelas de mecanismos, nomes de arquivos de runbook e prefixos de ticket estão fora de escopo.

Veja também

• Converter — Referência aprofundada
• Extraction
• Diff
• Pipeline HTML do Core