Migration von Dompdf zu NextPDF

Auf einen Blick

Diese Anleitung führt eine Dompdf-basierte Codebasis auf die Html-Pipeline von NextPDF um. Dompdf und NextPDF folgen demselben Ablauf — HTML laden, rendern, ein PDF ausgeben —, sodass sich die meisten Aufrufstellen mechanisch übertragen lassen. Die eigentliche Arbeit liegt in der Optionszuordnung und im Delta der CSS-Unterstützung. NextPDF und Dompdf sind unabhängige Engines; daher ist ein von Dompdf erzeugtes Layout kompatibel mit dem Ergebnis von NextPDF, aber nicht bytegenau identisch. Diese Anleitung behandelt die Verb-Zuordnung, die Optionsschlüssel-Zuordnung, die Verhaltensunterschiede und eine sichere Migrationsabfolge.

Die Unterstützung eines HTML/CSS-Features durch NextPDF garantiert nicht, dass ein bestimmtes Dompdf-Dokument pixelgenau nachgebildet wird. Die CSS-Unterstützungsmatrix ist die maßgebliche Quelle dafür, welche Features als Verified gelten. Diese Anleitung beschreibt Verhalten; sie behauptet keine visuelle Gleichwertigkeit.

Installation

composer require nextpdf/core:^3

Lassen Sie dompdf/dompdf während des Übergangs installiert (die sichere Migrationsabfolge betreibt beide nebeneinander, bis jede Aufrufstelle umgestellt ist), und entfernen Sie es erst, sobald die Umstellung abgeschlossen ist.

Konzeptioneller Überblick

Das Dompdf-Objekt von Dompdf ist eine einzelne Fassade, die das DOM, das Stylesheet, den Frame-Baum und die Canvas besitzt. NextPDF trennt diese Belange: Ein NextPDF\Core\Document verwaltet das Seitenmodell und die Ausgabe, und die Methode writeHtml() steuert die HTML-Pipeline. Es gibt keinen separaten zweiphasigen Schritt nach dem Muster „erst rendern, dann ausgeben“. writeHtml() setzt den Inhalt beim Schreiben direkt um; das Dokument geben Sie mit save(), output() oder getPdfData() aus.

Der Seiteninhalt, den NextPDF schreibt, ist Content-Stream-Malen gemäß ISO 32000-2 (ISO 32000-2 §8, iso32000_2_sec8#x1.x3.p14). Die Seitengeometrie, die die Papiergrößenoption steuert, wird auf die MediaBox des Seitenobjekts abgebildet (ISO 32000-2 §7, iso32000_2_sec7#x1.x104.p10). Diese Engine-Grundlagen teilt jeder konforme Writer. Der Layout-Algorithmus, der CSS in diesen Inhalt überführt, ist bei NextPDF jedoch eigenständig und unterscheidet sich von dem Dompdf-Algorithmus (siehe Verhaltensunterschiede).

API-Oberfläche

Die Html-API von NextPDF ist in der Referenz zum Html-Modul dokumentiert (automatisch aus PHPDoc erzeugt). Die unten verwendeten zentralen Einstiegspunkte sind: Document::createStandalone(), Document::writeHtml(string $html): static, Document::writeHtmlCell(...), Document::output(?string, OutputDestination), Document::save(string $path): void, Document::getPdfData(): string und das Wertobjekt NextPDF\Core\Config (pageSize, margins, fontsDirectory).

Zuordnung der API-Verben

Die unten genannten Namen der öffentlichen Dompdf-API sind anhand des öffentlichen Upstream-Repositorys (dompdf/dompdf, master) bestätigt — siehe den repo-internen Provenance-Sidecar _source-sidecar-upstream-api.md. Es wird kein Upstream-Dokumentationstext wiedergegeben.

Dompdf	NextPDF	Hinweise
new Dompdf($options)	Document::createStandalone($config)	Dompdf nimmt ein Options-Objekt entgegen; NextPDF nimmt ein NextPDF\Core\Config entgegen. Für langlebige Worker verwenden Sie DocumentFactory statt createStandalone().
$dompdf->loadHtml($html, $encoding)	$doc->writeHtml($html)	NextPDF behandelt Eingaben als UTF-8; transkodieren Sie Nicht-UTF-8-Eingaben vor dem Aufruf, statt ein Encoding-Argument zu übergeben.
$dompdf->loadHtmlFile($file)	$doc->writeHtml(file_get_contents($file))	NextPDF hat keine Datei-Lade-Variante; lesen Sie die Datei selbst, damit die I/O-Richtlinie in Ihrem Code bleibt.
$dompdf->setPaper($size, $orientation)	ConfigpageSize (ein PageSize-Wertobjekt)	Siehe die Option-Zuordnung.
$dompdf->render()	(implizit)	NextPDF setzt das Layout während writeHtml() um; es gibt keine separate Render-Phase. Entfernen Sie den Aufruf von render().
$dompdf->output()	$doc->getPdfData()	Liefert die PDF-Bytes.
$dompdf->stream($name, $opts)	$doc->output($name, OutputDestination::Download)	NextPDF trennt das Ziel über das OutputDestination-Enum.
$dompdf->setBasePath($p) / setProtocol() / setBaseHost()	(Ressourcenauflösung unterscheidet sich)	NextPDF löst relative Ressourcen gegen das Arbeitsset des Dokuments auf, nicht gegen ein Tripel aus Basis-path/protocol — siehe Verhaltensunterschiede.
$dompdf->addInfo($label, $value)	$doc->setTitle() / setAuthor() / Metadaten-API	Die formlosen Informationspaare von Dompdf werden auf die typisierten Metadaten-Setter abgebildet (ISO 32000-2 §14 Dokumentinformationen, iso32000_2_sec14#x1.x5.p5).
$dompdf->setHttpContext($ctx)	(keine Entsprechung)	NextPDF ruft entfernte Ressourcen nicht über einen Stream-Kontext ab; siehe Nicht unterstützt / keine direkte Entsprechung.

Codebeispiel — Schnellstart

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Document;

// Dompdf:
//   $dompdf = new Dompdf();
//   $dompdf->loadHtml('<h1>Invoice</h1>');
//   $dompdf->setPaper('A4', 'portrait');
//   $dompdf->render();
//   file_put_contents('out.pdf', $dompdf->output());

// NextPDF — the createStandalone() default page size is A4 portrait:
$doc = Document::createStandalone();
$doc->setTitle('Invoice');
$doc->addPage();
$doc->writeHtml('<h1>Invoice</h1>');
$doc->save(__DIR__ . '/out.pdf');

echo "Wrote out.pdf\n";

Codebeispiel — Produktion

Dies spiegelt examples/08-html-basic.php wider (die ausführbare Grundlage dieser Anleitung), mit einer vom Standard abweichenden expliziten Papiergröße und Rändern. Es entspricht einem setPaper() von Dompdf plus einer Randkonfiguration über Options.

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Contracts\OutputDestination;
use NextPDF\Core\Config;
use NextPDF\Core\Document;
use NextPDF\ValueObjects\Margin;
use NextPDF\ValueObjects\PageSize;

// Equivalent of: $dompdf->setPaper('letter','portrait') + margin options.
// US Letter portrait = 612 x 792 pt.
// Margin constructor order is (top, right, bottom, left) — all 0.5in here.
$config = new Config(
    pageSize: new PageSize(612.0, 792.0, 'Letter'),
    margins: new Margin(36.0, 36.0, 36.0, 36.0), // top,right,bottom,left; 0.5in in points
);

$doc = Document::createStandalone($config);
$doc->setTitle('Quarterly Report');
$doc->setAuthor('Finance');
$doc->addPage();

$html = <<<'HTML'
<h1 style="color:#1E3A8A;">Quarterly Report</h1>
<p>This report renders through the NextPDF Html pipeline. The CSS subset that
is <strong>Verified</strong> for production is the support-matrix authority,
not this page.</p>
<table border="1">
  <tr><th>Region</th><th>Total</th></tr>
  <tr><td>EMEA</td><td>1,204</td></tr>
</table>
HTML;

$doc->writeHtml($html);

// Equivalent of $dompdf->stream('report.pdf'):
$doc->output('report.pdf', OutputDestination::Download);

 RegionTotal EMEA1,204HTML;$doc->writeHtml($html);// Equivalent of $dompdf->stream('report.pdf'):$doc->output('report.pdf', OutputDestination::Download);">

Randfälle & Fallstricke

• Kein zweiphasiges Rendern. Dompdf-Code, der Zustand zwischen render() und output() inspiziert (zum Beispiel das Auslesen der Seitenanzahl), hat an genau dieser Nahtstelle keine Entsprechung in NextPDF. Fragen Sie das Dokument stattdessen nach writeHtml() ab.
• Encoding. NextPDF verzichtet auf den Parameter $encoding von Dompdf: Konvertieren Sie die Eingabe vor writeHtml() nach UTF-8. Die Übergabe von Latin-1-Bytes erzeugt Mojibake, keinen Fehler.
• Verbliebener render()-Aufruf. Ein übrig gebliebener Aufruf im Stil von $dompdf->render() hat keine Methode in NextPDF und führt zu einem fatalen „undefined method“. Löschen Sie ihn bei der Umstellung, statt ihn zu stubben.
• Inline-PHP. Das enable_php von Dompdf wertet <script type="text/php"> aus. NextPDF hat keine PHP-Ausführung im Dokument, und das ist Absicht (es ist eine Injektionsfläche). Verlagern Sie diese Logik in Ihr PHP vor writeHtml().
• Auflösung relativer Ressourcen. Dompdf löst <img src> gegen das Tripel aus Basis-path/protocol/host auf. NextPDF löst gegen das Arbeitsset des Dokuments auf. Übergeben Sie während der Migration absolute Pfade oder vorab aufgelöste Data-URIs, um die Variable zu entfernen.

Performance

writeHtml() setzt das Layout in einem einzigen Streaming-Durchgang um (ADR-001). Nach dem Layout wird kein zwischengeschaltetes Frame-Baum-Objekt vorgehalten, sodass der Spitzenspeicher die Dokumentgröße und nicht die Anzahl der DOM-Knoten widerspiegelt. Das Performance-Budget für das Beispiel dieser Anleitung ist wall_ms: 2000, peak_mb: 128. Große Dokumente: Teilen Sie das HTML entlang von addPage()-Grenzen auf, statt eine einzige Zeichenkette von mehreren Megabyte zu bauen.

Sicherheitshinweise

• Kein entferntes Abrufen über Stream-Kontext. NextPDF implementiert nicht den Remote-Abruf-Pfad von Dompdf über setHttpContext() / enable_remote. Lösen Sie entfernte Assets in Ihrer Anwendung auf und validieren Sie sie; übergeben Sie anschließend Bytes oder Data-URIs. Das entfernt die SSRF-Angriffsfläche, die enable_remote mit sich bringt.
• Keine Codeausführung im Dokument. Das Fehlen einer Entsprechung zu enable_php ist eine bewusste Härtung, keine Lücke.
• Dokumentmetadaten, die Sie über die typisierten Setter setzen, werden in das Informationswörterbuch / XMP gemäß ISO 32000-2 §14 geschrieben (iso32000_2_sec14#x1.x5.p5). Legen Sie dort keine Geheimnisse ab.

Konformität

Aussage	Spezifikation	Klausel	reference_id
Der Seiteninhalt ist Content-Stream-Malen im opaque/transparent-Modell.	ISO 32000-2	§8
Die Papiergröße wird auf den Grenzkasten des Seitenobjekts abgebildet.	ISO 32000-2	§7
HTML-Schriften werden als embedded/subset-Schriftprogramme geschrieben.	ISO 32000-2	§9
Die Verarbeitung von Leerraum / Zeilenumbruch ist engine-spezifisch.	CSS Text 3	§6.5

NextPDF erzeugt Inhalte gemäß ISO 32000-2. Es behauptet nicht, dass ein migriertes Dompdf-Dokument visuell identisch ist. Ein Wechsel des Renderers erfordert immer eine erneute Prüfung der Ausgabe.

Kommerzieller Kontext

Nicht zutreffend. Core deckt den hier beschriebenen HTML-zu-PDF-Migrationspfad ab.

Siehe auch

• Migrationsindex
• Von mPDF migrieren
• CSS-Unterstützungsmatrix
• Html-Modul

---

Migrationsdetails (R6-Pflichtabschnitte)

Für wen das gedacht ist

Teams, die dompdf/dompdf für serverseitiges HTML-zu-PDF einsetzen und auf die NextPDF-Engine umstellen möchten. Wenn Sie nur loadHtml / setPaper / render / output aufrufen, deckt die Verb-Zuordnung Ihre gesamte Oberfläche ab.

Umfang

Im Umfang sind: die Fassadenverben von Dompdf, die Options-Schlüssel, die Erwartungen an die CSS-Feature-Parität, die Ressourcenauflösung und die Metadaten. Außerhalb des Umfangs: die internen Objekte FrameTree/Canvas/Stylesheet von Dompdf (NextPDF hat keine öffentlichen Entsprechungen — migrieren Sie keinen Code, der darauf zugreift; ersetzen Sie ihn durch die öffentliche API).

Kompatibilitätszuordnung

Die Abdeckung ist Verhaltenskompatibilität, kein Drop-in-Shim. NextPDF hat kein Klassen-Shim für Dompdf (anders als der TCPDF-Pfad — siehe /migration/tcpdf-compat/). Schreiben Sie jede Aufrufstelle anhand der Verb-Zuordnung neu. Die Verified-Zeilen der CSS-Unterstützungsmatrix bestimmen die CSS-Feature-Erwartung vollständig. Diese Anleitung wiederholt nicht den Status jeder einzelnen Eigenschaft.

Option- und Konfigurationszuordnung

Dompdf-Option (Schlüssel / Setter)	NextPDF	Hinweise
default_paper_size / setDefaultPaperSize() ; setPaper($size,...)	Config->pageSize (PageSize VO)	Benannte Größen werden zu expliziten Punktmaßen; new PageSize(595.276, 841.890, 'A4') ist der Standard von createStandalone().
default_paper_orientation / setDefaultPaperOrientation()	tauschen Sie PageSize width/height	NextPDF hat kein Ausrichtungsflag; eine Querformatseite ist eine PageSize mit Breite > Höhe.
dpi / setDpi()	(kein globaler Regler)	NextPDF arbeitet in PDF-Punkten (1/72 Zoll); die Bildgrößenbestimmung erfolgt pro Bild, nicht über einen Dokument-DPI-Multiplikator. Rechnen Sie feste Pixelgrößen in Punkte um.
enable_remote / setIsRemoteEnabled()	(keine Entsprechung — bewusst so)	Lösen Sie entfernte Assets in Ihrem Code auf; siehe Sicherheitshinweise.
enable_html5_parser / setIsHtml5ParserEnabled()	(parst immer HTML)	Kein Schalter; der Parser ist die Pipeline.
enable_php / setIsPhpEnabled()	(keine Entsprechung — bewusst so)	PHP im Dokument wird nicht unterstützt; verlagern Sie die Logik aus dem Template heraus.
font_dir / setFontDir()	Config->fontsDirectory	Eine einzelne Zeichenkette für das Schriftenverzeichnis.
chroot	(in der App auflösen)	NextPDF nimmt keine Dateisystem-Jail-Option entgegen; führen Sie die Pfadvalidierung durch, bevor Sie Bytes übergeben.
default_font / setDefaultFont()	CSS-font-family / registrierte Schrift	Setzen Sie den Standard über Ihr Basis-Stylesheet oder die Schriftregistrierung, nicht über eine globale Option.
enable_font_subsetting / setIsFontSubsettingEnabled()	(setzt immer Subsets)	NextPDF bildet eingebettete Schriften immer als Subset (ISO 32000-2 §9, iso32000_2_sec9#x1.x45.p7); es gibt kein „Aus“ — ein Dompdf-Pfad mit ausgeschaltetem Flag hat keine Entsprechung und wird nicht benötigt.

Verhaltensunterschiede

• Layout-Engine. Dompdf und NextPDF sind unabhängige CSS-Layout-Implementierungen. Das Zusammenfassen von Leerraum und der Zeilenumbruch sind spezifiziert, aber von der Engine abhängig (CSS Text 3 §6.5, css_text_3#x1.x6.x5.p20). Rechnen Sie bei dichtem Text mit Unterschieden bei Zeilenumbruch und Paginierung. Erstellen Sie nach der Migration eine neue Baseline für die visuellen Diffs.
• Render-Nahtstelle. Keine zweiphasige Grenze aus render()/output() (siehe Randfälle).
• Ressourcenauflösung. Basis-Pfad/Protokoll/Host gegenüber dem Arbeitsset des Dokuments.
• DPI-Modell. Punkte gegenüber dem DPI-Multiplikator von Dompdf.
• Metadaten. Formlose Paare aus addInfo() gegenüber typisierten Settern (ISO 32000-2 §14, iso32000_2_sec14#x1.x5.p5).

Das sind dokumentierte Verhaltensunterschiede, keine Defekte in einer der beiden Engines.

Nicht unterstützt / keine direkte Entsprechung

• enable_php (PHP im Dokument) — absichtlich nicht vorhanden.
• setHttpContext() / enable_remote Remote-Abruf — absichtlich nicht vorhanden.
• Öffentlicher Zugriff auf FrameTree / Canvas / Stylesheet — keine öffentliche Entsprechung.
• dpi als dokumentweiter Multiplikator — nicht modelliert.

Code, der davon abhängt, lässt sich nicht direkt migrieren. Entfernen Sie ihn oder bilden Sie ihn gemäß den obigen Zeilen im Anwendungscode neu ab.

Sichere Migrationsabfolge

1. Fügen Sie nextpdf/core neben dompdf/dompdf hinzu (entfernen Sie Dompdf noch nicht).
2. Wählen Sie ein risikoarmes Dokument aus. Schreiben Sie seine Aufrufstelle mit der Verb-Zuordnung neu; löschen Sie den Aufruf von render().
3. Erzeugen Sie beide PDFs für dieselbe Eingabe und vergleichen Sie sie visuell. Behandeln Sie Unterschiede als erwartet (unabhängige Engines) und entscheiden Sie die Annahme je Dokument.
4. Konvertieren Sie die Optionsnutzung über die Option-Zuordnung; rechnen Sie DPI-abgeleitete Größen in Punkte um.
5. Lösen Sie remote/relative Assets vorab zu absoluten Pfaden oder Data-URIs auf, um die Auflösungsvariable zu entfernen.
6. Wiederholen Sie das je Dokument, vom geringsten zum höchsten Risiko. Lassen Sie beide Engines installiert, bis die letzte Aufrufstelle umgestellt ist.
7. Entfernen Sie dompdf/dompdf erst nach der letzten Umstellung aus composer.json.

Die Migration testen

• Erstellen Sie einen Snapshot der Dompdf-Ausgabe repräsentativer Dokumente vor der Codeänderung (Golden Inputs, keine Golden Bytes — die Bytes werden sich unterscheiden).
• Lassen Sie für jedes migrierte Dokument die Ausgabe von NextPDF durch Ihre eigene Abnahmeprüfung laufen (visueller Diff, Textextraktions-Assertions). Das Verhalten der eigenen HTML-Pipeline von NextPDF ist durch examples/08-html-basic.php und die Html-Suite des Core-Verzeichnisses tests/ abgedeckt. Ihre Migrationsabnahme ist dokumentspezifisch; es liegt in Ihrer Verantwortung, sie nachzuweisen.
• Fügen Sie je migriertem Dokument einen Regressionstest hinzu, damit ein künftiges Engine-Update erkannt wird.

Nachweis / Rückverfolgbarkeit

Jede Verhaltensaussage zu NextPDF auf dieser Seite ist durch einen repo-internen Test, ein Beispiel, eine Quellsignatur oder ein ADR gestützt — oder, sofern es sich um eine PDF-Formateigenschaft handelt, durch die RAG-fixierten Klauseln aus ISO 32000-2 / CSS in den Front-Matter-citations: und die Konformität-Tabelle. Das Verhalten von Dompdf wird nur als „unabhängige Engine — dokumentierte Unterschiede erwarten“ angeführt. Es wird keine Parität behauptet, die nicht durch ein repo-internes Artefakt belegt ist.

Verhaltensaussage zu NextPDF	Repo-interner Nachweis (Pfad)
createStandalone() erzeugt standardmäßig eine A4-Seite im Hochformat (595.276 × 841.890 pt).	src/Core/Config.php (Standard PageSize(595.276, 841.890, 'A4')); tests/Unit/Core/DocumentCreateStandaloneAndConfigWithersEdgeCaseTest.php (createStandaloneWithNullConfigBuildsDocumentWithA4Defaults).
writeHtml() setzt das Layout in einem einzigen Streaming-Durchgang um; nach dem Layout wird kein DOM vorgehalten.	docs/architecture/adr/ADR-001-stream-based-rendering-pipeline.md; src/Core/Concerns/HasTextOutput.php (writeHtml()).
writeHtml() erstellt automatisch die erste Seite, wenn keine vorhanden ist.	tests/Unit/Core/Concerns/DocumentTextOutputFontSubsettingAndBorderEdgeCaseTest.php (writeHtmlAutoCreatesFirstPageWhenNoPagesExist).
output() / save() / getPdfData() sind die Ausgabeverben (keine zweiphasige render/output).	src/Core/Concerns/HasOutput.php (output(), save(), getPdfData()); tests/Unit/Core/Concerns/DocumentOutputDestinationDispatchTest.php.
Das Ausgabeziel ist das NextPDF\Contracts\OutputDestination-Enum (Inline/Download/File/String).	src/Contracts/OutputDestination.php; tests/Unit/Core/Concerns/DocumentOutputDestinationDispatchTest.php.
HTML-Schriften werden immer als embedded/subset-Programme geschrieben.	tests/Unit/Core/Concerns/DocumentTextOutputFontSubsettingAndBorderEdgeCaseTest.php (recordUsedCharactersAffectsFontSubsetting); ISO 32000-2 §9 (Front-Matter-citations:).
Typisierte Metadaten-Setter (setTitle/setAuthor) ersetzen das formlose addInfo().	src/Core/Concerns/HasMetadata.php (setTitle(), setAuthor()); tests/Unit/Core/Concerns/DocumentInfoMetadataSetterBaselineTest.php.
End-to-End-HTML-Pipeline (die ausführbare Grundlage dieser Anleitung).	examples/08-html-basic.php; Core-tests/Unit/Html/-Suite.
Leerraum / Zeilenumbruch ist engine-spezifisch (Layout-Delta).	CSS Text 3 §6.5 (Front-Matter-citations: + Konformität).

Rollback

Weil beide Pakete bis zur finalen Umstellung installiert bleiben, bedeutet ein Rollback für eine noch nicht konvertierte Aufrufstelle, nur diese eine Aufrufstelle auf den Dompdf-Pfad zurückzusetzen. Nach der finalen Umstellung bedeutet ein Rollback, dompdf/dompdf und die vorherige Aufrufstelle aus der Versionskontrolle wiederherzustellen. Es ist keine Datenmigration beteiligt — nur Code.

Performance-Erwägungen

Siehe Performance. Das Einzeldurchgangsmodell bedeutet, dass die Migration keine Kosten für das Vorhalten eines Frame-Baums einführt. Die wesentliche Kostenänderung pro Dokument ist das eifrige erneute Auflösen von Assets (Schritt 5), das Sie cachen können.

Häufige Fallstricke

• render() stehen lassen (fatale undefinierte Methode).
• Nicht-UTF-8-Bytes übergeben, nachdem $encoding entfallen ist (stilles Mojibake).
• Bytegenau oder pixelgenau identische Ausgabe erwarten (unabhängige Engines — diese Anleitung behauptet nie einen Drop-in oder 100% Kompatibilität).
• Sich auf enable_php-Templates verlassen (die herausrefaktoriert werden müssen).
• Die CSS-Unterstützungsmatrix als beratend behandeln — sie ist die maßgebliche Quelle für die Erwartungen an Verified-Features.