Pro editie

Converter — Diepe referentie

In het kort

NextPDF\Pro\Converter exporteert een bestaande PDF naar gepositioneerde HTML, vereenvoudigde SVG of platte tekst, en segmenteert documentcontent in getypeerde structurele regio’s. Deze diepe referentie somt het publieke API-oppervlak, de matrix met operatordekking, het gedragscontract en de faalmodi op. Het is een exporteur voor contentextractie, geen pixelperfecte renderer.

Beschikbaarheid en licentiëring

Deze functionaliteit wordt geleverd in NextPDF Pro (nextpdf/pro) en wordt geactiveerd met een licentie-envelop op Pro-niveau. Een deployment zonder die rechten laadt de klassen van de functionaliteit niet. Vergelijk edities en vraag een licentie aan.

Geen enkele runtime-capaciteitsflag schermt deze module af. De converterklassen worden opgelost zodra het Pro-pakket is geïnstalleerd en gelicentieerd.

Publiek API-oppervlak

Symbool	Parameters	Standaardgedrag	Retourneert	Gooit of faalt met	Opmerkingen
`PdfToHtmlConverter::convert()`	`string $pdfData`, `?ConversionConfig $config = null`	Exporteert elke tekstdragende pagina naar één zelfstandig HTML5-document	`ConversionResult` (target `Html5`)	`InvalidArgumentException` wanneer `$pdfData` leeg is	Een null-config valt terug op `ConversionTarget::Html5`
`PdfToSvgConverter::convert()`	`string $pdfData`, `int $pageIndex = 0`, `?ConversionConfig $config = null`	Exporteert één pagina naar een zelfstandig SVG-document	`ConversionResult` (target `Svg`; `pageCount` is altijd 1)	`InvalidArgumentException` wanneer `$pdfData` leeg is	Een `$pageIndex` buiten bereik levert een SVG met alleen achtergrond op
`PdfToTextConverter::convert()`	`string $pdfData`	Extraheert gedecodeerde tekst uit alle pagina’s, gescheiden door een paginascheidingsmarkering	`ConversionResult` (target `PlainText`)	`InvalidArgumentException` wanneer `$pdfData` leeg is	Alleen dit target decodeert literal-string-escapes
`PdfToTextConverter::extractPage()`	`string $pdfData`, `int $pageIndex`	Extraheert gedecodeerde tekst voor één nulgebaseerde pagina	`string`	Gooit niet; retourneert `''` bij een ontbrekende pagina of lege invoer	Anders dan `convert()` geen bewaking op lege invoer
`DocumentSegmentationEngine::segment()`	`string $pdfData`	Classificeert paginacontent in getypeerde structurele segmenten met behulp van ruimtelijke en font-heuristieken	`NextPDF\Pro\Interop\V1\Segment\DocumentSegmentation`	`InvalidArgumentException` wanneer de invoer leeg is of de PDF-structuur niet geparset kan worden	Op regels gebaseerd; voert geen AI-inferentie uit
`ConversionConfig::__construct()`	`ConversionTarget $target`, `bool $embedFonts = false`, `bool $embedImages = true`, `float $scaleFactor = 1.0`, `string $cssClass = 'pdf-page'`	Onveranderlijke conversie-instellingen	`ConversionConfig`	—	`embedFonts` en `embedImages` worden geaccepteerd maar niet gebruikt in 3.1.0
`ConversionResult::size()`	—	Bytelengte van de geproduceerde uitvoer	`int`	—	Publieke readonly-velden: `output`, `target`, `pageCount`, `processingTimeMs`
`ConversionResult::isValid()`	—	Meldt of de uitvoer niet-leeg is	`bool`	—	HTML- en SVG-documentskeletten zijn nooit leeg; controleer in plaats daarvan `pageCount`
`ConversionTarget`	String-backed cases `Html5`, `Svg`, `PlainText`	Selecteert het exporttarget	`mimeType(): string`, `fileExtension(): string`	—	`fileExtension()` wijst naar `html`, `svg`, `txt`

Signatures van de entry-points:

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

Gedragscontract

De invoer bestaat uit ruwe PDF-bytes; de uitvoer is een ConversionResult-value-object. De drie export-converters delen één scanmodel: lokaliseer de grenzen stream/endstream, isoleer BT/ET-tekstblokken en parse de tekstweergeefoperatoren. Ze parsen de cross-reference-tabel niet en pakken gecomprimeerde streams niet uit. DocumentSegmentationEngine verschilt: die lost de trailer, catalog en pagina-boom op en pakt FlateDecode-paginacontent uit vóór de classificatie.

Operatordekking:

PDF-operator	HTML	SVG	Tekst
`Tj` (toon string)	ja	ja	ja
`TJ` (toon array)	ja	ja	ja
`'` (verplaats + toon)	nee	nee	ja
`Td` / `Tm` (positie)	ja	ja	n.v.t.
`Tf` (lettergrootte)	ja	ja	n.v.t.
`re` (rechthoek)	nee	ja	nee
`m` / `l` (lijn)	nee	ja	nee
`RG` (RGB-streek)	nee	ja (toegepast op rechthoek-/lijnstreek)	nee
krommen, arcering, clipping, afbeeldingen	nee	nee	nee

Positionering. Elk BT/ET-blok leidt één positie af uit zijn eerste Td- of Tm-match; Tm heeft voorrang wanneer beide voorkomen. De Y-as wordt omgeklapt van de PDF-gebruikersruimte naar de uitvoerruimte met de oorsprong linksboven. De lettergrootte valt terug op 12 pt wanneer er geen Tf aanwezig is.
Paginageometrie. HTML en SVG gaan uit van een A4-paginakader (595 x 842 pt) vermenigvuldigd met scaleFactor. De SVG-root draagt bijpassende viewBox-, breedte- en hoogte-attributen over een witte achtergrondrechthoek.
Streekkleur. RG-operatoren worden positioneel opgelost, dus een stream die de streekkleur meer dan eens verandert, kleurt elke rechthoek en lijn met de meest recente voorafgaande operator. Componenten worden vastgezet op het bereik 0..1 vóór de hex-conversie. De vulling van een rechthoek is altijd zwart; de rg-vuloperator wordt niet geëvalueerd.
String-decodering. Het tekst-target decodeert literal-string-escapes volgens ISO 32000-2:2020 §7.3.4.2: benoemde escapes, octale \ddd-codes gemaskeerd tot één byte, backslash-regelvoortzettingen en het verwijderen van een losstaande backslash. HTML- en SVG-targets geven de ruwe bytes tussen haakjes weer na HTML- of XML-escaping; ze decoderen geen escapes.
Uitvoersamenstelling. Het tekst-target voegt blokteksten samen met een spatie, en pagina’s met --- Page Break --- omkaderd door lege regels. Het HTML-target geeft per tekstblok één absoluut gepositioneerde <div> weer binnen een container per pagina die de geconfigureerde CSS-klasse en een data-page-attribuut draagt.
Determinisme. Voor identieke invoer en configuratie zijn de geproduceerde HTML-, SVG- of tekstbytes stabiel. processingTimeMs is een wall-clock-meting en valt buiten het deterministische oppervlak.

Randgevallen en faalmodi

Lege invoer: elk convert()- en segment()-entry-point genereert InvalidArgumentException (“PDF data must not be empty”). Er wordt geen gedeeltelijke uitvoer geproduceerd. extractPage() is de uitzondering: die retourneert '' zonder te gooien.
Streams zonder BT/ET worden door de HTML- en tekstconverters overgeslagen. Een PDF die alleen zulke streams bevat, levert een pageCount van nul op met een lege tekstuitvoer of een HTML-skelet zonder pagina’s.
isValid() controleert alleen op niet-lege uitvoer. HTML- en SVG-converters geven altijd een documentskelet weer, dus isValid() blijft true zelfs wanneer er geen tekst is gevonden; gebruik pageCount (HTML, tekst) om lege extractie te detecteren.
FlateDecode-content wordt niet uitgepakt door de drie export-converters. Uitsluitend gecomprimeerde PDF’s exporteren via hen weinig tot geen content. segment() pakt FlateDecode-paginastreams wél uit.
segment() begrenst decompressie op streamgrootte, compressieverhouding en een cumulatief budget. Een stream die een plafond doorbreekt, degradeert naar lege paginacontent in plaats van het geheugen uit te putten; het gooit niet.
segment() genereert InvalidArgumentException wanneer de trailer, cross-reference-offset, document-catalog of pagina-boom niet opgelost kan worden.
Pagina-indexering verschilt per converter. HTML- en tekstconverters tellen alleen tekstdragende streams; de SVG-converter telt streams die een herkende grafische of tekstoperator bevatten. Dezelfde $pageIndex kan daarom naar verschillende streams verwijzen.
Numerieke kerning-aanpassingen van TJ worden weggegooid; array-strings worden samengevoegd zonder spatiëring tussen glyphs.
Glyph-naar-Unicode-mapping wordt niet toegepast. Tekst gezet in fonts met aangepaste encodings exporteert als de ruwe bytereeks.
Geroteerde tekst, niet-tekst-transformaties en kolomstroom worden benaderd door first-match-positionering en reproduceren de oorspronkelijke lay-out mogelijk niet.
In deze module vindt geen cryptografische bewerking plaats, dus FIPS-modus heeft geen modulespecifiek gedrag.

Conformiteit

NextPDF documenteert functionaliteit ten opzichte van de geciteerde clausules. Ondersteuningsverklaringen beschrijven geïmplementeerd gedrag; het zijn geen resultaten van conformiteitstests en geen certificeringen, en NextPDF beschikt over geen enkele certificering.

Claim	Spec-clausule	Status
`Tj`-tekstweergeefoperator geparset	ISO 32000-2:2020 §9.4	Geverifieerd (unit-suite)
`TJ`-array-tekstweergeefoperator geparset	ISO 32000-2:2020 §9.4	Geverifieerd (unit-suite)
`'`-verplaats-en-toon-operator geparset (alleen tekst-target)	ISO 32000-2:2020 §9.4	Geverifieerd (unit-suite)
Literal-string-escapes gedecodeerd (alleen tekst-target)	ISO 32000-2:2020 §7.3.4.2	Geïmplementeerd; bytes worden ongewijzigd geretourneerd, charset-interpretatie is downstream
`re`, `m`, `l` padconstructie herkend (SVG-target)	ISO 32000-2:2020 §8.5.2	Gedeeltelijk: subset zonder krommen, sluiting of evaluatie van de painting-modus
Volledige tekststatusmachine en paginarendering	—	Niet ondersteund (buiten scope)

De converter parse’t tekstweergeefoperatoren om content te herstellen; hij implementeert niet de volledige tekststatusmachine, dus de glyph-positionering is benaderend in plaats van spec-exact.

Ontwikkelnotities

Het parsen is lineair in de PDF-bytelengte. Het geheugengebruik volgt de invoer plus de geproduceerde uitvoerstring. De front matter performance_budget is de referentie per aanroep voor een typisch kantoordocument.
De converters parsen niet-vertrouwde PDF-bytes met begrensd strpos/substr-scannen. Ze voeren geen ingebedde JavaScript uit en volgen geen externe referenties. Behandel geëxporteerde HTML als niet-vertrouwde content en escape deze voor de bestemming.
HTML-uitvoer wordt geëscaped met htmlspecialchars (ENT_QUOTES, HTML5); SVG-tekst wordt XML-geëscaped. De geconfigureerde cssClass wordt geëscaped vóór de uitvoer.
Config-gebruik: scaleFactor geldt voor de HTML- en SVG-targets; cssClass geldt alleen voor HTML; embedFonts en embedImages zijn gereserveerd en momenteel ongebruikt; het veld target overschrijft niet het eigen uitvoerformaat van een converter.
De export-converters worden geleverd sinds 1.9.0; DocumentSegmentationEngine wordt geleverd sinds 2.1.0 en ondersteunt de Pro-MCP-tool segment_document en het Interop-segmentatiecontract.
PdfPageExtractor en PdfPageData in dezelfde namespace zijn intern voor de segmentatie-engine en zijn geen publieke API.

Publicatiegrens

Deze pagina documenteert uitsluitend extern waarneembaar gedrag en het ondersteunde publieke API-oppervlak. Interne namespace-paden, helper-klassen, mechanismetabellen, runbook-bestandsnamen en ticket-prefixen vallen buiten scope.