Pro edição

Converter — Referência Profunda

Visão geral

NextPDF\Pro\Converter exporta um PDF existente para HTML posicionado, SVG simplificado ou texto simples, e segmenta o conteúdo do documento em regiões estruturais tipadas. Esta referência profunda enumera a superfície da API pública, a matriz de cobertura de operadores, o contrato de comportamento e os modos de falha. É um exportador de extração de conteúdo, não um renderizador pixel-perfect.

Disponibilidade & licenciamento

Este recurso é distribuído 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 edições e obtenha uma licença.

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

Superfície da API pública

Símbolo	Parâmetros	Comportamento padrão	Retorna	Lança ou falha com	Observações
`PdfToHtmlConverter::convert()`	`string $pdfData`, `?ConversionConfig $config = null`	Exporta cada página com texto para um único documento HTML5 autocontido	`ConversionResult` (destino `Html5`)	`InvalidArgumentException` quando `$pdfData` está vazio	Config nula usa `ConversionTarget::Html5` por padrão
`PdfToSvgConverter::convert()`	`string $pdfData`, `int $pageIndex = 0`, `?ConversionConfig $config = null`	Exporta uma página para um documento SVG independente	`ConversionResult` (destino `Svg`; `pageCount` é sempre 1)	`InvalidArgumentException` quando `$pdfData` está vazio	Um `$pageIndex` fora do intervalo produz um SVG apenas com plano de fundo
`PdfToTextConverter::convert()`	`string $pdfData`	Extrai o texto decodificado de todas as páginas, separado por um marcador de quebra de página	`ConversionResult` (destino `PlainText`)	`InvalidArgumentException` quando `$pdfData` está vazio	Apenas este destino decodifica escapes de literal-string
`PdfToTextConverter::extractPage()`	`string $pdfData`, `int $pageIndex`	Extrai o texto decodificado de uma página com índice baseado em zero	`string`	Não lança; retorna `''` para uma página inexistente ou entrada vazia	Diferente de `convert()`, sem proteção contra entrada vazia
`DocumentSegmentationEngine::segment()`	`string $pdfData`	Classifica o conteúdo da página em segmentos estruturais tipados usando heurísticas espaciais e de fonte	`NextPDF\Pro\Interop\V1\Segment\DocumentSegmentation`	`InvalidArgumentException` quando a entrada está vazia ou a estrutura do PDF não pode ser analisada	Baseado em regras; não realiza inferência de IA
`ConversionConfig::__construct()`	`ConversionTarget $target`, `bool $embedFonts = false`, `bool $embedImages = true`, `float $scaleFactor = 1.0`, `string $cssClass = 'pdf-page'`	Configurações de conversão imutáveis	`ConversionConfig`	—	`embedFonts` e `embedImages` são aceitos, mas não consumidos na 3.1.0
`ConversionResult::size()`	—	Comprimento em bytes da saída produzida	`int`	—	Campos públicos readonly: `output`, `target`, `pageCount`, `processingTimeMs`
`ConversionResult::isValid()`	—	Informa se a saída é não vazia	`bool`	—	Os invólucros de documento HTML e SVG nunca são vazios; verifique `pageCount` em vez disso
`ConversionTarget`	Casos com base em string `Html5`, `Svg`, `PlainText`	Seleciona o destino de exportação	`mimeType(): string`, `fileExtension(): string`	—	`fileExtension()` mapeia para `html`, `svg`, `txt`

Assinaturas dos pontos 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 comportamento

As entradas são bytes brutos de PDF; as saídas são um objeto de valor ConversionResult. Os três conversores de exportação compartilham um modelo de varredura: localizar os limites stream/endstream, isolar os blocos de texto BT/ET e analisar os operadores de exibição de texto. Eles não analisam a tabela de referência cruzada e não descompactam fluxos compactados. O DocumentSegmentationEngine é diferente: ele resolve o trailer, o catálogo e a árvore de páginas, e descompacta o conteúdo de página FlateDecode antes da classificação.

Cobertura de operadores:

Operador PDF	HTML	SVG	Texto
`Tj` (mostrar string)	sim	sim	sim
`TJ` (mostrar array)	sim	sim	sim
`'` (mover + mostrar)	não	não	sim
`Td` / `Tm` (posição)	sim	sim	n/d
`Tf` (tamanho da fonte)	sim	sim	n/d
`re` (retângulo)	não	sim	não
`m` / `l` (linha)	não	sim	não
`RG` (traço RGB)	não	sim (aplicado ao traço de retângulo/linha)	não
curvas, sombreamento, recorte, imagens	não	não	não

Posicionamento. Cada bloco BT/ET resolve uma posição a partir de sua primeira correspondência Td ou Tm; Tm tem precedência quando ambos aparecem. O eixo Y é invertido do espaço do usuário PDF para o espaço de saída no canto superior esquerdo. O tamanho da fonte assume 12 pt por padrão quando nenhum Tf está presente.
Geometria da página. HTML e SVG assumem uma caixa de página A4 (595 x 842 pt) multiplicada por scaleFactor. A raiz do SVG carrega atributos viewBox, largura e altura correspondentes sobre um retângulo de fundo branco.
Cor do traço. Os operadores RG são resolvidos posicionalmente, portanto um fluxo que altera a cor do traço mais de uma vez colore cada retângulo e linha pelo operador precedente mais recente. Os componentes são limitados ao intervalo 0..1 antes da conversão para hexadecimal. O preenchimento do retângulo é sempre preto; o operador de preenchimento rg não é avaliado.
Decodificação de string. O destino de texto decodifica escapes de literal-string conforme a ISO 32000-2:2020 §7.3.4.2: escapes nomeados, códigos octais \ddd mascarados para um byte, continuações de linha por barra invertida e remoção de barra invertida isolada. Os destinos HTML e SVG emitem os bytes brutos entre parênteses após o escape de HTML ou XML; eles não decodificam escapes.
Montagem da saída. O destino de texto une os textos de bloco com um espaço, e as páginas com --- Page Break --- emoldurado por linhas em branco. O destino HTML emite um <div> posicionado de forma absoluta por bloco de texto dentro de um contêiner por página que carrega a classe CSS configurada e um atributo data-page.
Determinismo. Para entrada e configuração idênticas, os bytes de HTML, SVG ou texto produzidos são estáveis. processingTimeMs é uma medição de tempo de relógio e é excluído da superfície determinística.

Casos extremos & modos de falha

Entrada vazia: todo ponto de entrada convert() e segment() gera InvalidArgumentException (“PDF data must not be empty”). Nenhuma saída parcial é produzida. extractPage() é a exceção: retorna '' sem lançar.
Fluxos sem BT/ET são ignorados pelos conversores de HTML e texto. Um PDF que contém apenas esses fluxos produz um pageCount zero com uma saída de texto vazia ou um invólucro HTML sem páginas.
isValid() apenas verifica se a saída é não vazia. Os conversores de HTML e SVG sempre emitem um invólucro de documento, portanto isValid() permanece true mesmo quando nenhum texto foi encontrado; use pageCount (HTML, texto) para detectar extração vazia.
O conteúdo FlateDecode não é descompactado pelos três conversores de exportação. PDFs apenas compactados exportam pouco ou nenhum conteúdo por meio deles. segment() descompacta os fluxos de página FlateDecode.
segment() limita a descompactação por tamanho de fluxo, taxa de compressão e um orçamento cumulativo. Um fluxo que ultrapassa um teto degrada para conteúdo de página vazio em vez de esgotar a memória; ele não lança.
segment() gera InvalidArgumentException quando o trailer, o offset de referência cruzada, o catálogo do documento ou a árvore de páginas não podem ser resolvidos.
A indexação de páginas difere por conversor. Os conversores de HTML e texto contam apenas fluxos com texto; o conversor de SVG conta fluxos que contêm qualquer operador de gráficos ou texto reconhecido. O mesmo $pageIndex pode, portanto, endereçar fluxos diferentes.
Os ajustes numéricos de kerning de TJ são descartados; as strings do array são concatenadas sem espaçamento entre glifos.
O mapeamento de glifo para Unicode não é aplicado. O texto definido em fontes com codificações personalizadas é exportado como a sequência de bytes bruta.
Texto rotacionado, transformações não textuais e fluxo em colunas são aproximados pelo posicionamento da primeira correspondência e podem não reproduzir o layout original.
Nenhuma operação criptográfica ocorre neste módulo, portanto o modo FIPS não tem comportamento específico do módulo.

Conformidade

O NextPDF documenta os recursos em relação às cláusulas citadas. As declarações de suporte descrevem o comportamento implementado; elas não são resultados de teste de conformidade nem certificações, e o NextPDF não possui certificação.

Alegação	Cláusula da especificação	Status
Operador de exibição de texto `Tj` analisado	ISO 32000-2:2020 §9.4	Verificado (suíte de unidade)
Operador de exibição de texto em array `TJ` analisado	ISO 32000-2:2020 §9.4	Verificado (suíte de unidade)
Operador de mover-e-mostrar `'` analisado (apenas destino de texto)	ISO 32000-2:2020 §9.4	Verificado (suíte de unidade)
Escapes de literal-string decodificados (apenas destino de texto)	ISO 32000-2:2020 §7.3.4.2	Implementado; bytes retornados como estão, a interpretação de charset é feita a jusante
Construção de caminho `re`, `m`, `l` reconhecida (destino SVG)	ISO 32000-2:2020 §8.5.2	Parcial: subconjunto sem curvas, fechamento ou avaliação de modo de pintura
Máquina de estado de texto completa e renderização de página	—	Sem suporte (fora do escopo)

O conversor analisa os operadores de exibição de texto para recuperar o conteúdo; ele não implementa a máquina de estado de texto completa, portanto o posicionamento dos glifos é aproximado em vez de exato segundo a especificação.

Notas de desenvolvimento

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.
Os conversores analisam bytes de PDF não confiáveis com varredura limitada por strpos/substr. Eles não executam nenhum JavaScript incorporado e não seguem nenhuma referência externa. Trate o HTML exportado como conteúdo não confiável e faça o escape dele para seu destino.
A saída HTML sofre escape com htmlspecialchars (ENT_QUOTES, HTML5); o texto SVG sofre escape XML. A cssClass configurada sofre escape antes da emissão.
Consumo de configuração: scaleFactor se aplica aos destinos HTML e SVG; cssClass se aplica apenas ao HTML; embedFonts e embedImages são reservados e atualmente não utilizados; o campo target não substitui o formato de saída próprio de um conversor.
Os conversores de exportação são distribuídos desde a 1.9.0; DocumentSegmentationEngine é distribuído desde a 2.1.0 e sustenta a ferramenta MCP segment_document do Pro e o contrato de segmentação Interop.
PdfPageExtractor e PdfPageData no mesmo namespace são internos ao mecanismo de segmentação e não são API pública.

Limite de publicação

Esta página documenta apenas o comportamento observável externamente e a superfície da API pública com suporte. Caminhos de namespace internos, classes auxiliares, tabelas de mecanismos, nomes de arquivos de runbook e prefixos de tickets estão fora do escopo.