Convertitore

In breve

NextPDF\Pro\Converter legge un PDF esistente ed esporta il suo contenuto verso uno di tre target basati su testo: HTML posizionato, SVG semplificato o testo semplice. È un esportatore a estrazione di contenuto, non un renderer PDF pixel-perfect.

Disponibilità e licenza

Questa funzionalità è fornita in NextPDF Pro (nextpdf/pro) e si attiva con un envelope di licenza di fascia Pro. Un deployment privo di tale abilitazione non carica le classi della funzionalità. Confrontare le edizioni e ottenere una licenza.

Nessun flag di capacità a runtime governa questo modulo. Le classi del Converter si risolvono ogni volta che il pacchetto Pro è installato e caricato tramite autoload.

Installazione

composer require nextpdf/pro:^3

Panoramica concettuale

Il Converter analizza gli operatori di visualizzazione del testo all’interno di un content stream PDF — Tj, TJ e ' secondo ISO 32000-2:2020 §9.4 — e ricostruisce una rappresentazione approssimata di ciascuna pagina. Legge il posizionamento dagli operatori di testo Td e Tm e la dimensione del font da Tf, quindi mappa i punti sulle coordinate di output.

Vengono esposti tre converter, uno per ciascun ConversionTarget:

• PdfToHtmlConverter racchiude ogni pagina in un contenitore posizionato ed emette elementi <div> con posizionamento assoluto per ciascun blocco di testo. L’output è un documento HTML5 autonomo.
• PdfToSvgConverter analizza un insieme limitato di operatori di disegno (rettangoli tramite re, linee tramite m/l) oltre al testo, ed emette gli elementi <rect>, <line> e <text> corrispondenti per una pagina.
• PdfToTextConverter estrae solo il testo decodificato, pagina per pagina, separato da un marcatore di interruzione di pagina.

Si tratta di un esportatore deliberatamente delimitato. Approssima la posizione del testo; non riflette il contenuto, non rasterizza e non riproduce tracciati vettoriali, sfumature, ritaglio, trasparenza o immagini incorporate. Per il rendering ad alta fedeltà da HTML a PDF nella direzione opposta, usare la pipeline HTML del Core.

Perché funziona così

Un PDF memorizza il testo come operatori di visualizzazione di glifi posizionati, non come caratteri semantici, quindi non esiste un testo di documento affidabile da rileggere. Il Converter analizza perciò direttamente gli operatori del content stream — Tj, TJ, ', oltre a Td, Tm e Tf per la collocazione — e ricostruisce un layout approssimato invece di riflettere o rasterizzare la pagina. Questa scansione delimitata è ciò che mantiene l’esportazione lineare rispetto alla lunghezza in byte, deterministica per input identici e sicura su byte non attendibili senza eseguire logica incorporata. Fissa anche il tetto onesto: i glifi non vengono rimappati a ritroso su Unicode, quindi i font con codifica personalizzata vengono esportati come byte grezzi e la fedeltà visiva esatta resta fuori ambito. Contesto di progettazione: Perché il testo in un PDF non è davvero testo.

Contratto di comportamento

• Input. Byte PDF grezzi (string). Una stringa vuota solleva InvalidArgumentException.
• Output. Un value object ConversionResult che contiene la stringa prodotta, il ConversionTarget, il numero di pagine elaborate e una misurazione del tempo di elaborazione.
• Copertura. L’esportazione del testo (Tj/TJ/') è il percorso verificato, esercitato dalla suite di unit test. L’esportazione SVG copre solo rettangoli, linee rette e testo. Il colore di tratto RGB non viene ancora propagato all’output SVG.
• Determinismo. Per un input e una configurazione identici, il flusso di byte HTML, SVG o testo prodotto è stabile. Il campo processingTimeMs è una misurazione di tipo wall e non fa parte della superficie deterministica.
• Codifica. L’output HTML viene sottoposto a escape con htmlspecialchars; l’output SVG viene sottoposto a escape XML. Le comuni sequenze di escape delle stringhe PDF (\n, \r, \t, \(, \), \\) vengono decodificate per il target di testo.

Superficie API pubblica

Tipo	Tipologia	Membri chiave
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

Esempio di codice — Avvio rapido

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

Esempio di codice — Produzione

<?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;
}

Casi limite e insidie

• Un PDF privo di blocchi di testo BT/ET produce un output vuoto o limitato alla sola intelaiatura della pagina; i PDF acquisiti tramite scanner (composti da sole immagini) non producono testo perché non vi è alcuna fase di OCR.
• PdfToSvgConverter converte una sola pagina alla volta, selezionata da $pageIndex; un indice fuori intervallo produce un flusso di pagina vuoto.
• Il posizionamento è approssimato. Il testo collocato con trasformazioni non testuali, il testo ruotato o il flusso a colonne potrebbero non riprodurre il layout visivo originale.
• La mappatura da glifo a Unicode non viene applicata; il testo proveniente da font che usano codifiche personalizzate potrebbe essere esportato come la sequenza di byte grezzi.

Prestazioni

L’analisi è lineare rispetto alla lunghezza in byte del PDF. La memoria segue l’input più la stringa di output prodotta. Il front-matter performance_budget è il riferimento per invocazione per un tipico documento d’ufficio.

Note sulla sicurezza

Il converter analizza byte PDF non attendibili con scansione delimitata strpos/substr sugli operatori di testo; non esegue JavaScript incorporato né segue riferimenti esterni. Trattare l’HTML esportato come contenuto non attendibile e sottoporlo a escape in modo appropriato per la sua destinazione. Vedere il modello di sicurezza del Core.

Conformità

Dichiarazione	Clausola spec	Stato
Operatore di visualizzazione testo Tj analizzato	ISO 32000-2:2020 §9.4	Verificato (suite di unit test)
Operatore di visualizzazione testo array TJ analizzato	ISO 32000-2:2020 §9.4	Verificato (suite di unit test)
Fedeltà completa di pagina vettoriale/raster	—	Non supportato (fuori ambito)

Fallback / alternativa Core

Non esiste alcun equivalente Core per l’esportazione di PDF. Per la direzione diretta (creare un PDF a partire da HTML), la pipeline HTML del Core open source è il percorso supportato. Vedere /modules/core/html/.

Nota sui confini Enterprise

Il Converter è un esportatore di testo/forme di fascia Pro. Non esegue OCR, ricostruzione semantica o comprensione dei documenti. Questi sono temi distinti e non sono forniti da questo modulo.

Confine di pubblicazione

Questa pagina documenta solo il comportamento osservabile dall’esterno e la superficie API pubblica supportata. I percorsi di namespace interni, le classi helper, le tabelle dei meccanismi, i nomi dei file di runbook e i prefissi dei ticket sono fuori ambito.

Vedere anche

• Convertitore — Riferimento approfondito
• Estrazione
• Diff
• Pipeline HTML del Core