Pro Edition

Konverter

Auf einen Blick

NextPDF\Pro\Converter liest ein vorhandenes PDF und exportiert seinen Inhalt in eines von drei textbasierten Zielen: positioniertes HTML, vereinfachtes SVG oder reinen Text. Es handelt sich um einen Inhalts-Extraktions-Exporter, keinen pixelgenauen PDF-Renderer.

Verfügbarkeit & Lizenzierung

Diese Funktion ist in NextPDF Pro (nextpdf/pro) enthalten und wird mit einem Lizenzumschlag der Pro-Stufe aktiviert. Eine Bereitstellung ohne diese Berechtigung lädt die Klassen der Funktion nicht. Editionen vergleichen und Lizenz erwerben.

Kein Laufzeit-Fähigkeits-Flag schränkt dieses Modul ein. Die Converter-Klassen werden aufgelöst, sobald das Pro-Paket installiert und automatisch geladen ist.

Installation

composer require nextpdf/pro:^3

Konzeptioneller Überblick

Der Converter parst die textanzeigenden Operatoren innerhalb eines PDF-Content-Streams — Tj, TJ und ' gemäß ISO 32000-2:2020 §9.4 — und baut eine ungefähre Darstellung jeder Seite wieder auf. Er liest die Positionierung aus den Text-Operatoren Td und Tm und die Schriftgröße aus Tf und bildet anschließend Punkte auf Ausgabekoordinaten ab.

Es werden drei Konverter bereitgestellt, einer je ConversionTarget:

PdfToHtmlConverter umschließt jede Seite mit einem positionierten Container und gibt für jeden Textlauf absolut positionierte <div>-Elemente aus. Die Ausgabe ist ein in sich geschlossenes HTML5-Dokument.
PdfToSvgConverter parst einen begrenzten Satz an Zeichenoperatoren (Rechtecke über re, Linien über m/l) plus Text und gibt passende <rect>-, <line>- und <text>-Elemente für eine Seite aus.
PdfToTextConverter extrahiert nur den dekodierten Text, Seite für Seite, getrennt durch einen Seitenumbruch-Marker.

Dies ist ein bewusst begrenzter Exporter. Er nähert die Textposition an; er führt keinen Reflow durch, er rasterisiert nicht und er reproduziert keine Vektorpfade, Schattierungen, Beschneidungen, Transparenzen oder eingebetteten Bilder. Für HTML-nach-PDF-Rendering in voller Wiedergabetreue in der umgekehrten Richtung verwenden Sie die Core-HTML-Pipeline.

Warum es so funktioniert

Ein PDF speichert Text als positionierte glyphenanzeigende Operatoren, nicht als semantische Zeichen, sodass es keinen verlässlichen Dokumenttext gibt, der zurückgelesen werden könnte. Der Converter scannt daher die Content-Stream-Operatoren direkt — Tj, TJ, ' sowie Td, Tm und Tf für die Platzierung — und baut ein ungefähres Layout wieder auf, statt die Seite umzubrechen oder zu rasterisieren. Dieser begrenzte Scan hält den Export linear in der Bytelänge, deterministisch für identische Eingabe und sicher gegenüber nicht vertrauenswürdigen Bytes, ohne eingebettete Logik auszuführen. Er setzt außerdem die ehrliche Obergrenze: Glyphen werden nicht auf Unicode zurückgebildet, sodass Schriften mit benutzerdefinierter Kodierung als rohe Bytes exportiert werden und die exakte visuelle Wiedergabetreue außerhalb des Geltungsbereichs bleibt. Designhintergrund: Warum der Text in einem PDF nicht wirklich Text ist.

Verhaltensvertrag

Eingabe. Rohe PDF-Bytes (string). Ein leerer String löst InvalidArgumentException aus.
Ausgabe. Ein ConversionResult-Wertobjekt, das den erzeugten String, das ConversionTarget, die Anzahl der verarbeiteten Seiten und eine Verarbeitungszeit-Messung enthält.
Abdeckung. Der Textexport (Tj/TJ/') ist der verifizierte Pfad, abgedeckt durch die Unit-Suite. Der SVG-Export deckt nur Rechtecke, gerade Linien und Text ab. Die RGB-Strichfarbe wird noch nicht in die SVG-Ausgabe übernommen.
Determinismus. Für identische Eingabe und Konfiguration ist der erzeugte HTML-, SVG- oder Text-Byte-Stream stabil. Das Feld processingTimeMs ist eine Wanduhr-Messung und nicht Teil der deterministischen Oberfläche.
Kodierung. Die HTML-Ausgabe ist mit htmlspecialchars escaped; die SVG-Ausgabe ist XML-escaped. Gängige PDF-String-Escape-Sequenzen (\n, \r, \t, $, $, \\) werden für das Textziel dekodiert.

Öffentliche API-Oberfläche

Typ	Art	Wichtige Mitglieder
`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`

Codebeispiel — Schnellstart

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

Codebeispiel — Produktion

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

Randfälle & Fallstricke

Ein PDF ohne BT/ET-Textblöcke liefert leere oder nur seitenschalenhafte Ausgabe; gescannte (reine Bild-)PDFs erzeugen keinen Text, weil es keinen OCR-Schritt gibt.
PdfToSvgConverter konvertiert jeweils eine einzelne Seite, ausgewählt über $pageIndex; ein Index außerhalb des Bereichs liefert einen leeren Seiten-Stream.
Die Positionierung ist näherungsweise. Text, der mit Nicht-Text-Transformen platziert ist, gedrehter Text oder Spaltenfluss reproduzieren ihr ursprüngliches visuelles Layout möglicherweise nicht.
Eine Glyph-zu-Unicode-Zuordnung wird nicht angewendet; Text aus Schriften mit benutzerdefinierten Kodierungen kann als rohe Bytefolge exportiert werden.

Performance

Das Parsen ist linear in der PDF-Bytelänge. Der Speicher folgt der Eingabe plus dem erzeugten Ausgabe-String. Das performance_budget-Frontmatter ist der Referenzwert je Aufruf für ein typisches Bürodokument.

Sicherheitshinweise

Der Converter parst nicht vertrauenswürdige PDF-Bytes mit begrenztem strpos-/substr-Scannen über Text-Operatoren; er führt kein eingebettetes JavaScript aus und folgt keinen externen Referenzen. Behandeln Sie exportiertes HTML als nicht vertrauenswürdigen Inhalt und escapen Sie es angemessen für sein Ziel. Siehe das Core-Sicherheitsmodell.

Konformität

Behauptung	Spec-Klausel	Status
`Tj` textanzeigender Operator geparst	ISO 32000-2:2020 §9.4	Verifiziert (Unit-Suite)
`TJ`-Array-Operator zum Textanzeigen geparst	ISO 32000-2:2020 §9.4	Verifiziert (Unit-Suite)
Volle Vektor-/Raster-Seitentreue	—	Nicht unterstützt (außerhalb des Geltungsbereichs)

Core-Rückfalloption / Alternative

Für den PDF-Export gibt es kein Core-Äquivalent. Für die Vorwärtsrichtung (Erstellen eines PDF aus HTML) ist die quelloffene Core-HTML-Pipeline der unterstützte Weg. Siehe /modules/core/html/.

Hinweis zur Enterprise-Abgrenzung

Der Converter ist ein Text-/Form-Exporter der Pro-Stufe. Er führt kein OCR, keine semantische Rekonstruktion und kein Dokumentenverständnis durch. Das sind separate Anliegen und werden von diesem Modul nicht bereitgestellt.

Veröffentlichungsgrenze

Diese Seite dokumentiert ausschließlich extern beobachtbares Verhalten und die unterstützte öffentliche API-Oberfläche. Interne Namespace-Pfade, Helferklassen, Mechanismus-Tabellen, Runbook-Dateinamen und Ticket-Präfixe sind außerhalb des Geltungsbereichs.