Pro edizione

Converter — Riferimento approfondito

In breve

NextPDF\Pro\Converter esporta un PDF esistente in HTML posizionato, SVG semplificato o testo semplice e segmenta il contenuto del documento in regioni strutturali tipizzate. Questo riferimento approfondito elenca la superficie API pubblica, la matrice di copertura degli operatori, il contratto di comportamento e le modalità di errore. È un esportatore di estrazione dei contenuti, non un renderer perfetto al pixel.

Disponibilità e licenza

Questa funzionalità è inclusa in NextPDF Pro (nextpdf/pro) e si attiva con un envelope di licenza di livello Pro. Un deployment privo di tale titolo non carica le classi della funzionalità. Confronta le edizioni e ottieni una licenza.

Nessun flag di capacità a runtime applica un gate a questo modulo. Le classi del converter vengono risolte ogni volta che il pacchetto Pro è installato e provvisto di licenza.

Superficie API pubblica

Simbolo	Parametri	Comportamento predefinito	Restituisce	Solleva o fallisce con	Note
`PdfToHtmlConverter::convert()`	`string $pdfData`, `?ConversionConfig $config = null`	Esporta ogni pagina contenente testo in un unico documento HTML5 autonomo	`ConversionResult` (target `Html5`)	`InvalidArgumentException` quando `$pdfData` è vuoto	Con config null il valore predefinito è `ConversionTarget::Html5`
`PdfToSvgConverter::convert()`	`string $pdfData`, `int $pageIndex = 0`, `?ConversionConfig $config = null`	Esporta una pagina in un documento SVG autonomo	`ConversionResult` (target `Svg`; `pageCount` è sempre 1)	`InvalidArgumentException` quando `$pdfData` è vuoto	Un `$pageIndex` fuori intervallo produce un SVG con solo lo sfondo
`PdfToTextConverter::convert()`	`string $pdfData`	Estrae il testo decodificato da tutte le pagine, separato da un marcatore di interruzione di pagina	`ConversionResult` (target `PlainText`)	`InvalidArgumentException` quando `$pdfData` è vuoto	Solo questa destinazione decodifica gli escape delle stringhe letterali
`PdfToTextConverter::extractPage()`	`string $pdfData`, `int $pageIndex`	Estrae il testo decodificato per una singola pagina con indice a base zero	`string`	Non solleva eccezioni; restituisce `''` per una pagina mancante o input vuoto	A differenza di `convert()`, nessuna protezione contro l’input vuoto
`DocumentSegmentationEngine::segment()`	`string $pdfData`	Classifica il contenuto della pagina in segmenti strutturali tipizzati mediante euristiche spaziali e sui font	`NextPDF\Pro\Interop\V1\Segment\DocumentSegmentation`	`InvalidArgumentException` quando l’input è vuoto o la struttura del PDF non può essere analizzata	Basato su regole; non esegue alcuna inferenza AI
`ConversionConfig::__construct()`	`ConversionTarget $target`, `bool $embedFonts = false`, `bool $embedImages = true`, `float $scaleFactor = 1.0`, `string $cssClass = 'pdf-page'`	Impostazioni di conversione immutabili	`ConversionConfig`	—	`embedFonts` e `embedImages` sono accettati ma non utilizzati nella 3.1.0
`ConversionResult::size()`	—	Lunghezza in byte dell’output prodotto	`int`	—	Campi pubblici readonly: `output`, `target`, `pageCount`, `processingTimeMs`
`ConversionResult::isValid()`	—	Indica se l’output è non vuoto	`bool`	—	Gli scheletri dei documenti HTML e SVG non sono mai vuoti; verificare invece `pageCount`
`ConversionTarget`	Casi con backing a stringa `Html5`, `Svg`, `PlainText`	Seleziona la destinazione di esportazione	`mimeType(): string`, `fileExtension(): string`	—	`fileExtension()` mappa a `html`, `svg`, `txt`

Firme dei punti di ingresso:

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

Contratto di comportamento

Gli input sono byte PDF grezzi; l’output è un value object ConversionResult. I tre converter di esportazione condividono un modello di scansione: individuano i confini stream/endstream, isolano i blocchi di testo BT/ET e analizzano gli operatori di visualizzazione del testo. Non analizzano la tabella dei riferimenti incrociati e non decomprimono gli stream compressi. DocumentSegmentationEngine si differenzia: risolve il trailer, il catalog e l’albero delle pagine e decomprime il contenuto di pagina FlateDecode prima della classificazione.

Copertura degli operatori:

Operatore PDF	HTML	SVG	Testo
`Tj` (mostra stringa)	sì	sì	sì
`TJ` (mostra array)	sì	sì	sì
`'` (sposta + mostra)	no	no	sì
`Td` / `Tm` (posizione)	sì	sì	n/d
`Tf` (dimensione font)	sì	sì	n/d
`re` (rettangolo)	no	sì	no
`m` / `l` (linea)	no	sì	no
`RG` (tratto RGB)	no	sì (applicato al tratto di rettangoli/linee)	no
curve, sfumature, clipping, immagini	no	no	no

Posizionamento. Ogni blocco BT/ET risolve una posizione dalla prima corrispondenza Td o Tm; Tm ha la precedenza quando compaiono entrambi. L’asse Y viene invertito dallo spazio utente PDF allo spazio di output in alto a sinistra. La dimensione del font è per impostazione predefinita 12 pt quando non è presente alcun Tf.
Geometria della pagina. HTML e SVG assumono un riquadro di pagina A4 (595 x 842 pt) moltiplicato per scaleFactor. La radice SVG riporta gli attributi viewBox, larghezza e altezza corrispondenti su un rettangolo di sfondo bianco.
Colore del tratto. Gli operatori RG vengono risolti in base alla posizione, quindi uno stream che cambia più volte il colore del tratto colora ogni rettangolo e linea in base all’operatore precedente più recente. I componenti vengono limitati all’intervallo 0..1 prima della conversione esadecimale. Il riempimento del rettangolo è sempre nero; l’operatore di riempimento rg non viene valutato.
Decodifica delle stringhe. La destinazione testuale decodifica gli escape delle stringhe letterali secondo ISO 32000-2:2020 §7.3.4.2: escape denominati, codici ottali \ddd mascherati a un byte, continuazioni di riga con backslash e rimozione dei backslash isolati. Le destinazioni HTML e SVG emettono i byte grezzi tra parentesi dopo l’escaping HTML o XML; non decodificano gli escape.
Assemblaggio dell’output. La destinazione testuale unisce i testi dei blocchi con uno spazio e le pagine con --- Page Break --- incorniciato da righe vuote. La destinazione HTML emette un <div> con posizionamento assoluto per ciascun blocco di testo all’interno di un contenitore per pagina che riporta la classe CSS configurata e un attributo data-page.
Determinismo. A parità di input e configurazione, i byte HTML, SVG o testo prodotti sono stabili. processingTimeMs è una misurazione del tempo reale ed è escluso dalla superficie deterministica.

Casi limite e modalità di errore

Input vuoto: ogni punto di ingresso convert() e segment() solleva InvalidArgumentException (“PDF data must not be empty”). Non viene prodotto alcun output parziale. extractPage() è l’eccezione: restituisce '' senza sollevare eccezioni.
Gli stream privi di BT/ET vengono ignorati dai converter HTML e testo. Un PDF che contiene solo tali stream produce un pageCount pari a zero con un output di testo vuoto o uno scheletro HTML privo di pagine.
isValid() verifica soltanto che l’output sia non vuoto. I converter HTML e SVG emettono sempre uno scheletro di documento, quindi isValid() resta true anche quando non è stato trovato alcun testo; usare pageCount (HTML, testo) per rilevare un’estrazione vuota.
Il contenuto FlateDecode non viene decompresso dai tre converter di esportazione. I PDF interamente compressi esportano poco o nessun contenuto attraverso di essi. segment() invece decomprime gli stream di pagina FlateDecode.
segment() limita la decompressione in base alla dimensione per stream, al rapporto di compressione e a un budget cumulativo. Uno stream che supera un limite massimo degrada a contenuto di pagina vuoto anziché esaurire la memoria; non solleva eccezioni.
segment() solleva InvalidArgumentException quando il trailer, l’offset dei riferimenti incrociati, il catalog del documento o l’albero delle pagine non possono essere risolti.
L’indicizzazione delle pagine differisce tra i converter. I converter HTML e testo contano solo gli stream contenenti testo; il converter SVG conta gli stream che contengono un qualsiasi operatore grafico o di testo riconosciuto. Lo stesso $pageIndex può quindi indirizzare stream diversi.
Le regolazioni numeriche di crenatura di TJ vengono scartate; le stringhe dell’array vengono concatenate senza spaziatura tra i glifi.
La mappatura glifo-Unicode non viene applicata. Il testo composto con font che utilizzano codifiche personalizzate viene esportato come sequenza di byte grezza.
Il testo ruotato, le trasformazioni non testuali e il flusso a colonne vengono approssimati mediante il posizionamento alla prima corrispondenza e potrebbero non riprodurre il layout originale.
In questo modulo non avviene alcuna operazione crittografica, quindi la modalità FIPS non presenta alcun comportamento specifico del modulo.

Conformità

NextPDF documenta le funzionalità rispetto alle clausole citate. Le dichiarazioni di supporto descrivono il comportamento implementato; non sono risultati di test di conformità né certificazioni, e NextPDF non detiene alcuna certificazione.

Dichiarazione	Clausola della specifica	Stato
Operatore di visualizzazione del testo `Tj` analizzato	ISO 32000-2:2020 §9.4	Verificato (suite di unit test)
Operatore di visualizzazione del testo ad array `TJ` analizzato	ISO 32000-2:2020 §9.4	Verificato (suite di unit test)
Operatore sposta-e-mostra `'` analizzato (solo destinazione testuale)	ISO 32000-2:2020 §9.4	Verificato (suite di unit test)
Escape delle stringhe letterali decodificati (solo destinazione testuale)	ISO 32000-2:2020 §7.3.4.2	Implementato; i byte vengono restituiti così come sono, l’interpretazione del charset è a valle
Costruzione di percorsi `re`, `m`, `l` riconosciuta (destinazione SVG)	ISO 32000-2:2020 §8.5.2	Parziale: sottoinsieme senza curve, chiusura o valutazione della modalità di disegno
Macchina a stati completa del testo e rendering della pagina	—	Non supportato (fuori ambito)

Il converter analizza gli operatori di visualizzazione del testo per recuperare i contenuti; non implementa la macchina a stati completa del testo, pertanto il posizionamento dei glifi è approssimativo anziché esatto secondo specifica.

Note di sviluppo

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.
I converter analizzano byte PDF non attendibili con una scansione limitata strpos/substr. Non eseguono alcun JavaScript incorporato e non seguono alcun riferimento esterno. Trattare l’HTML esportato come contenuto non attendibile ed effettuarne l’escaping per la destinazione.
L’output HTML viene sottoposto a escaping con htmlspecialchars (ENT_QUOTES, HTML5); il testo SVG viene sottoposto a escaping XML. La cssClass configurata viene sottoposta a escaping prima dell’emissione.
Utilizzo della configurazione: scaleFactor si applica alle destinazioni HTML e SVG; cssClass si applica solo a HTML; embedFonts e embedImages sono riservati e attualmente inutilizzati; il campo target non sovrascrive il formato di output proprio di un converter.
I converter di esportazione sono inclusi a partire dalla 1.9.0; DocumentSegmentationEngine è incluso a partire dalla 2.1.0 e supporta lo strumento MCP Pro segment_document e il contratto di segmentazione Interop.
PdfPageExtractor e PdfPageData nello stesso namespace sono interni al motore di segmentazione e non fanno parte dell’API pubblica.

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 di supporto, le tabelle dei meccanismi, i nomi dei file di runbook e i prefissi dei ticket sono fuori ambito.