Converter

In het kort

NextPDF\Pro\Converter leest een bestaande PDF en exporteert de inhoud ervan naar een van drie tekstgebaseerde doelen: gepositioneerde HTML, vereenvoudigde SVG of platte tekst. Het is een content-extractie-exporter, geen pixelnauwkeurige PDF-renderer.

Beschikbaarheid en licenties

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

Geen runtime-mogelijkheidsvlag bewaakt deze module. De Converter-klassen worden geresolveerd zodra het Pro-pakket is geïnstalleerd en ge-autoload.

Installatie

composer require nextpdf/pro:^3

Conceptueel overzicht

De Converter parseert de tekstweergaveoperatoren in een PDF-contentstream — Tj, TJ en ' volgens ISO 32000-2:2020 §9.4 — en herbouwt een benaderende weergave van elke pagina. Deze leest positionering uit de Td- en Tm-tekst- operatoren en de lettergrootte uit Tf, en wijst vervolgens punten toe aan uitvoercoördinaten.

Er worden drie converters blootgesteld, één per ConversionTarget:

• PdfToHtmlConverter wikkelt elke pagina in een gepositioneerde container en zendt absoluut gepositioneerde <div>-elementen uit voor elke tekstrun. De uitvoer is een op zichzelf staand HTML5-document.
• PdfToSvgConverter parseert een beperkte set tekenoperatoren (rechthoeken via re, lijnen via m/l) plus tekst, en zendt overeenkomstige <rect>-, <line>- en <text>-elementen uit voor één pagina.
• PdfToTextConverter extraheert alleen de gedecodeerde tekst, pagina voor pagina, gescheiden door een paginaeindmarkering.

Dit is een bewust begrensde exporter. Deze benadert de tekstpositie; deze herverdeelt niet, rasteriseert niet en reproduceert geen vector- paden, schaduwen, knipping, transparantie of ingebedde afbeeldingen. Voor HTML-naar-PDF-rendering met volledige getrouwheid in de tegengestelde richting gebruik je de Core HTML-pijplijn.

Waarom het zo werkt

Een PDF slaat tekst op als gepositioneerde glyph-weergaveoperatoren, niet als semantische tekens, dus er is geen betrouwbare documenttekst om terug te lezen. De Converter scant daarom rechtstreeks de contentstream-operatoren — Tj, TJ, ', plus Td, Tm en Tf voor plaatsing — en herbouwt een benaderende lay-out in plaats van de pagina te herverdelen of te rasteriseren. Die begrensde scan houdt de export lineair in bytelengte, deterministisch voor identieke invoer en veilig op niet-vertrouwde bytes zonder ingebedde logica uit te voeren. Het legt ook het eerlijke plafond vast: glyphs worden niet terug-gemapt naar Unicode, dus lettertypen met aangepaste codering exporteren als ruwe bytes en exacte visuele getrouwheid blijft buiten bereik. Ontwerpachtergrond: Waarom de tekst in een PDF niet echt tekst is.

Gedragscontract

• Invoer. Ruwe PDF-bytes (string). Een lege string werpt InvalidArgumentException.
• Uitvoer. Een ConversionResult-waarde-object dat de geproduceerde string bevat, het ConversionTarget, het aantal verwerkte pagina’s en een verwerkingstijdmeting.
• Dekking. Tekstexport (Tj/TJ/') is het geverifieerde pad, getest door de unit suite. SVG-export dekt alleen rechthoeken, rechte lijnen en tekst. De RGB-strokekleur wordt nog niet doorgegeven aan de SVG-uitvoer.
• Determinisme. Voor identieke invoer en configuratie is de geproduceerde HTML-, SVG- of tekstbytestream stabiel. Het processingTimeMs-veld is een wand- meting en maakt geen deel uit van het deterministische oppervlak.
• Codering. HTML-uitvoer wordt ge-htmlspecialchars-escaped; SVG-uitvoer wordt XML-escaped. Veelvoorkomende PDF-string-escapesequenties (\n, \r, \t, \(, \), \\) worden gedecodeerd voor het tekstdoel.

Publiek API-oppervlak

Type	Soort	Belangrijkste leden
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

Codevoorbeeld — Snelstart

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

Codevoorbeeld — Productie

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

Randgevallen en valkuilen

• Een PDF zonder BT/ET-tekstblokken levert lege of alleen-pagina-shell-uitvoer op; gescande (alleen-afbeelding-)PDF’s produceren geen tekst omdat er geen OCR-stap is.
• PdfToSvgConverter converteert één pagina per keer, geselecteerd door $pageIndex; een index buiten bereik levert een lege paginastream op.
• Positionering is benaderend. Tekst die met niet-teksttransformaties is geplaatst, geroteerde tekst of kolomflow reproduceert mogelijk niet de oorspronkelijke visuele lay-out.
• Glyph-naar-Unicode-mapping wordt niet toegepast; tekst uit lettertypen die aangepaste coderingen gebruiken, kan worden geëxporteerd als de ruwe bytesequentie.

Prestaties

Parsing is lineair in de PDF-bytelengte. Geheugen volgt de invoer plus de geproduceerde uitvoerstring. De performance_budget-front-matter is de referentie per aanroep voor een typisch kantoordocument.

Beveiligingsnotities

De converter parseert niet-vertrouwde PDF-bytes met begrensd strpos-/substr- scannen over tekstoperatoren; deze voert geen ingebedde JavaScript uit en volgt geen externe verwijzingen. Behandel geëxporteerde HTML als niet-vertrouwde inhoud en escape deze op de juiste manier voor de bestemming. Zie het Core-beveiligingsmodel.

Conformiteit

Claim	Spec-clausule	Status
Tj-tekstweergaveoperator geparseerd	ISO 32000-2:2020 §9.4	Geverifieerd (unit suite)
TJ-array-tekstweergaveoperator geparseerd	ISO 32000-2:2020 §9.4	Geverifieerd (unit suite)
Volledige vector-/rasterpaginagetrouwheid	—	Niet ondersteund (buiten bereik)

Core-fallback / alternatief

Er is geen Core-equivalent voor PDF-export. Voor de voorwaartse richting (een PDF maken vanuit HTML) is de open-source Core HTML-pijplijn het ondersteunde pad. Zie /modules/core/html/.

Enterprise-grensnotitie

De Converter is een tekst-/vormexporter op Pro-niveau. Deze voert geen OCR, semantische reconstructie of documentbegrip uit. Dat zijn aparte aangelegenheden en worden niet door deze module geleverd.

Publicatiegrens

Deze pagina documenteert alleen extern waarneembaar gedrag en het ondersteunde publieke API-oppervlak. Interne namespace-paden, helperklassen, mechanismetabellen, runbook-bestandsnamen en ticketprefixen vallen buiten bereik.

Zie ook

• Converter — Diepgaande referentie
• Extraction
• Diff
• Core HTML pipeline