Migration von mPDF zu NextPDF

Auf einen Blick

Diese Anleitung beschreibt die Migration einer mPDF-basierten Codebasis zum NextPDF-Core. Der zentrale mPDF-Aufruf ist WriteHTML(), der direkt Document::writeHtml() entspricht. Die eigentliche Arbeit besteht darin, das Konstruktor-Konfigurationsarray zuzuordnen (mPDF konfiguriert alles über ein einziges assoziatives Array, das an new Mpdf([...]) übergeben wird) und das Delta bei der Schriftbehandlung zu berücksichtigen. NextPDF und mPDF sind unabhängige Engines; ein migriertes Dokument ist daher kompatibel mit der mPDF-Ausgabe, aber nicht byteweise identisch. Diese Anleitung behandelt die Verb-Zuordnung, die Zuordnung des Konfigurationsarrays, das Schrift-Delta, das Delta bei der CSS-Unterstützung, die Verhaltensunterschiede und eine sichere Abfolge.

Die CSS-Unterstützungsmatrix ist die maßgebliche Quelle dafür, welche HTML-/CSS-Funktionen als „Verified“ eingestuft sind. Diese Anleitung beschreibt Verhalten; sie behauptet keine visuelle Übereinstimmung mit mPDF.

Installation

composer require nextpdf/core:^3

Behalten Sie mpdf/mpdf während des Übergangs installiert. Entfernen Sie es nach der finalen Umstellung (siehe sichere Migrationsabfolge).

Konzeptioneller Überblick

Das Mpdf-Objekt von mPDF ist eine große Fassade. Ein Konstruktor-Array übernimmt die Konfiguration; WriteHTML() und die Seitenverben (AddPage, SetHTMLHeader, SetHTMLFooter) steuern die Ausgabe. NextPDF trennt die Konfiguration in das unveränderliche Value Object NextPDF\Core\Config und steuert den Inhalt mit Document::writeHtml(). Es gibt keinen Konstruktor-„mode“-String. NextPDF parst das HTML, das Sie übergeben, und gibt das Dokument anschließend mit save(), output() oder getPdfData() aus.

Schriften: mPDF liefert ein Schriftverzeichnis plus eine fontdata-Zuordnung und einen Fallback-Satz aus „Core Fonts“. NextPDF löst Schriften über ein einzelnes Schriftverzeichnis plus CSS-font-family-Abgleich auf und bettet Schriften immer als Teilmenge ein (ISO 32000-2 §9, iso32000_2_sec9#x1.x45.p7). Schriftabgleich und Fallback unterscheiden sich je nach Engine (CSS Fonts 4 §5.5, css_fonts_4#x1.x5.x5.x1.p13), daher kann die Glyphenersetzung abweichen. Das ist das wichtigste sichtbare Delta; es wird im Delta bei der Schriftbehandlung behandelt.

API-Oberfläche

Die HTML-API von NextPDF ist die Referenz des Html-Moduls. Die wichtigsten Einstiegspunkte sind: Document::createStandalone(), Document::writeHtml(string $html): static, Document::writeHtmlCell(...), Document::addPage(), Document::output(?string, OutputDestination), Document::save(string $path): void, Document::getPdfData(): string sowie das Value Object NextPDF\Core\Config.

Verb-Zuordnung der API

Die folgenden öffentlichen mPDF-Methodennamen wurden anhand des öffentlichen Upstream-Repositorys geprüft (mpdf/mpdf, development) — siehe das Provenance-Sidecar _source-sidecar-upstream-api.md im Repository. Es wird kein Upstream-Dokumentationstext reproduziert.

mPDF	NextPDF	Hinweise
`new Mpdf([...])`	`Document::createStandalone($config)`	Das mPDF-Konfigurationsarray wird `NextPDF\Core\Config` zugeordnet; siehe Konfigurationszuordnung. Verwenden Sie `DocumentFactory` für langlebige Worker.
`$mpdf->WriteHTML($html)`	`$doc->writeHtml($html)`	Direkte Zuordnung. Das zweite Argument `$mode` von mPDF (vollständiges Dokument, reines CSS oder Element) hat keine Entsprechung in NextPDF — übergeben Sie vollständiges HTML.
`$mpdf->WriteFixedPosHTML(...)`	`$doc->writeHtmlCell(...)`	Positionierter und dimensionierter HTML-Bereich; ordnen Sie die Argumente x/y/width/height zu.
`$mpdf->AddPage(...)`	`$doc->addPage()`	Die mPDF-Overrides pro Aufruf für orientation/format/Rand sind in NextPDF keine Argumente; ändern Sie stattdessen das Dokumentmodell zwischen den Aufrufen.
`$mpdf->SetHTMLHeader($html)` / `SetHTMLFooter($html)`	Header/Footer über die Layout-API	Laufende mPDF-HTML-Header werden dem Header/Footer-Mechanismus von NextPDF zugeordnet, nicht Inline-HTML am Anfang des Bodys.
`$mpdf->Output($name, $dest)`	`$doc->output($name, OutputDestination::…)`	mPDF-Zielzeichen (`I`/`D`/`F`/`S`) werden dem `OutputDestination`-Enum zugeordnet (`Inline`/`Download`/file über `save()`/string über `getPdfData()`).
`$mpdf->Output('','S')`	`$doc->getPdfData()`	Liefert Bytes.
`$mpdf->Output($path,'F')`	`$doc->save($path)`	Schreibt in eine Datei unter dem angegebenen Pfad.
`$mpdf->SetTitle($t)`	`$doc->setTitle($t)`	Landet im Info-Dictionary / XMP gemäß ISO 32000-2 §14 (`iso32000_2_sec14#x1.x5.p5`).
`$mpdf->SetProtection($perms,...)`	`$doc->setEncryption(...)` (Security-API)	Berechtigungen sind Reader-kooperativ, keine Zugriffskontrolle — siehe Sicherheitshinweise.

Codebeispiel — Schnellstart

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

// mPDF:
//   $mpdf = new \Mpdf\Mpdf();
//   $mpdf->WriteHTML('<h1>Invoice</h1>');
//   $mpdf->Output('out.pdf', \Mpdf\Output\Destination::FILE);

// NextPDF — default page 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

Dieses Beispiel deckt sich mit examples/04-text-and-fonts.php, der lauffähigen Grundlage für die Schriftbehandlungskonzepte in dieser Anleitung. Es verwendet eine explizite Seitengröße, Ränder und einen Inhaltskörper, der die Schriftauswahl beansprucht.

<?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: new Mpdf(['format'=>'A4','margin_left'=>20, ...]).
// Margin constructor order is (top, right, bottom, left) — NOT L,R,T,B.
$config = new Config(
    pageSize: new PageSize(595.276, 841.890, 'A4'),
    margins: new Margin(16.0, 20.0, 16.0, 20.0), // top,right,bottom,left in points
    fontsDirectory: __DIR__ . '/fonts',
);

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

$html = <<<'HTML'
<h1 style="font-family:'DejaVu Sans';color:#1E3A8A;">Quarterly Report</h1>
<p>Body text resolves through CSS font-family matching against the configured
fonts directory. mPDF's fontdata map has no direct analogue — register the
family via CSS and the fonts directory instead.</p>
HTML;

$doc->writeHtml($html);

// Equivalent of $mpdf->Output('report.pdf', Destination::DOWNLOAD):
$doc->output('report.pdf', OutputDestination::Download);

Grenzfälle & Stolperfallen

$mode-Argument bei WriteHTML. Das WriteHTML($html, $mode) von mPDF (2 = nur CSS, 1 = Element) hat keine Entsprechung. Binden Sie Ihr CSS in das HTML ein, das Sie übergeben; es gibt keine Abfolge „erst CSS schreiben, dann Body schreiben“.
Overrides pro AddPage. mPDF lässt zu, dass AddPage() format/orientation mitten im Dokument per Argumenten ändert. NextPDF addPage() nimmt keine solchen Argumente; Größenänderungen werden über das Dokumentmodell gesteuert, nicht über den Seitenaufruf.
Header-/Footer-HTML. Laufende mPDF-Header sind HTML-Fragmente, die separat registriert werden; fügen Sie sie nicht in den Body ein. Ordnen Sie sie dem Header/Footer-Mechanismus von NextPDF zu.
Schriftnamen. mPDF normalisiert Schriftnamen über seine fontdata/core-font-Tabelle. NextPDF gleicht die CSS-Eigenschaft font-family gegen das Schriftverzeichnis ab; ein mPDF-Alias, der zuvor stillschweigend aufgelöst wurde, benötigt möglicherweise eine explizite @font-face/family.
Zielzeichen (Destination characters). 'I'/'D'/'F'/'S' werden nicht akzeptiert; verwenden Sie das OutputDestination-Enum oder save()/getPdfData().

Performance

writeHtml() arbeitet in einem Durchgang (ADR-001); der Spitzenspeicherbedarf folgt der Dokumentgröße, nicht einem im Speicher gehaltenen DOM. Budget für das Beispiel dieser Anleitung: wall_ms: 2000, peak_mb: 128. Verteilen Sie bei langen Dokumenten den Inhalt über mehrere addPage() statt über einen einzigen riesigen String. Das ist dieselbe Empfehlung, die für das Chunking mit $mode von mPDF gilt, hier aber über das Seitenmodell ausgedrückt.

Sicherheitshinweise

Berechtigungen sind Reader-kooperativ. SetProtection() → setEncryption() bietet Vertraulichkeit, keine Zugriffskontrolle: ISO-Berechtigungsbits hängen von einem kooperierenden Reader ab. Stellen Sie Verschlüsselung Nutzern gegenüber nicht als Zugriffskontrolle dar.
Metadaten. SetTitle() und Dokumentinfos landen im Informations-Dictionary / XMP gemäß ISO 32000-2 §14 (iso32000_2_sec14#x1.x5.p5); speichere dort niemals Geheimnisse.
NextPDF führt keine im Dokument enthaltenen Skripte aus; keine mPDF-Direktive aktiviert das hier.

Konformität

Aussage	Spezifikation	Klausel
Schriften werden als embedded/subset-Schriftprogramme geschrieben.	ISO 32000-2	§9
Seitenformat/margins werden der Seitenbegrenzungs-Box zugeordnet.	ISO 32000-2	§7
Titel-/Schutzmetadaten landen im Info-Dictionary / XMP.	ISO 32000-2	§14
Schriftabgleich / Fallback ist engine-spezifisch.	CSS Fonts 4	§5.5

NextPDF erzeugt ISO 32000-2-Inhalt; es behauptet keine visuelle Identität mit mPDF. Eine Änderung des Renderers erfordert eine erneute Prüfung der Ausgabe.

Kommerzieller Kontext

Nicht zutreffend. Core deckt den hier beschriebenen mPDF-Migrationspfad ab.

Siehe auch

Migrationsdetails (R6 erforderliche Abschnitte)

Für wen das gedacht ist

Teams, die mpdf/mpdf für serverseitiges HTML-zu-PDF einsetzen. Wenn Ihre Oberfläche new Mpdf([...]) + WriteHTML + Output (+ optional Header/Footer) ist, decken die Verb-Zuordnung und die Konfigurationszuordnung diesen Fall ab.

Geltungsbereich

Im Geltungsbereich: das Konstruktor-Konfigurationsarray von Mpdf, WriteHTML/Output/AddPage, Header/Footer, Schriften, Schutz, Metadaten. Außerhalb des Geltungsbereichs: interne mPDF-Klassen und die Hilfs-APIs für QR/Barcode/Wasserzeichen (ordnen Sie diese den entsprechenden NextPDF-Modulen zu — Barcode, Graphics — hier nicht behandelt).

Kompatibilitätszuordnung

Verhaltenskompatibilität, kein Drop-in-Shim: Es gibt keinen Klassen-Shim für Mpdf. Jede Aufrufstelle wird umgeschrieben. Die Erwartungen an CSS-Funktionen richten sich nach den als „Verified“ markierten Zeilen der CSS-Unterstützungsmatrix.

Zuordnung des Konstruktor-Konfigurationsarrays

Die mPDF-Konfigurationsschlüssel wurden anhand des öffentlichen Upstream-Repositorys geprüft (mpdf/mpdf, development). Es wird kein Upstream-Dokumentationstext reproduziert.

mPDF-Konfigurationsschlüssel	NextPDF	Hinweise
`mode`	(keine Entsprechung)	Der Mode-String von mPDF (`'utf-8'`, `'c'`, `'+aCJK'`, …) wählt das Font-/Script-Verhalten aus. NextPDF arbeitet immer mit Unicode; CJK wird über die Schriftauswahl behandelt, nicht über einen Mode. Lassen Sie den Schlüssel weg.
`format`	`Config->pageSize` (`PageSize` VO)	Benannte Formate werden zu expliziten Punktmaßen; Arrays `[w,h]` bilden auf ein `PageSize` ab.
`orientation`	`PageSize` width/height vertauschen	Kein Ausrichtungs-Flag; Querformat = width > height.
`default_font_size`	CSS-Basisschriftgröße	Setzen Sie sie über Ihr Basis-Stylesheet, nicht über einen Konstruktorschlüssel.
`default_font`	CSS `font-family` / registrierte Schrift	Setzen Sie die Standardfamilie über CSS / Schriftregistrierung.
`margin_left` / `margin_right` / `margin_top` / `margin_bottom`	`Config->margins` (`Margin` VO) in Punkt	Ein `Margin`-Value-Object; seine Konstruktorreihenfolge ist `Margin(top, right, bottom, left)` (prüfen Sie gegen `src/ValueObjects/Margin.php`), nicht die mPDF-Schlüsselreihenfolge.
`margin_header` / `margin_footer`	Header/Footer-Versatz über die Layout-API	Ordnen Sie dies der Header/Footer-Konfiguration von NextPDF zu, nicht Konstruktorschlüsseln.

Delta bei der Schriftbehandlung

Einzelnes Schriftverzeichnis. Die Schriftverzeichnisliste von mPDF + die fontdata-Zuordnung + der Core-Font-Fallback werden durch Config->fontsDirectory plus CSS-font-family-Abgleich ersetzt.
Immer Teilmenge (subset). NextPDF bettet Schriften immer als Teilmenge ein (ISO 32000-2 §9, iso32000_2_sec9#x1.x45.p7); die Subset-Flags von mPDF haben keine Entsprechung und werden nicht benötigt.
Der Abgleich ist engine-spezifisch. Schriftabgleich und Fallback unterscheiden sich je nach Engine (CSS Fonts 4 §5.5, css_fonts_4#x1.x5.x5.x1.p13); ein mPDF-Schriftalias benötigt möglicherweise eine explizite @font-face oder einen exakten Familiennamen. Erstellen Sie nach der Migration eine neue Baseline für das Glyphen-Rendering; Ersetzungsunterschiede sind zu erwarten, aber keine Defekte.

Verhaltensunterschiede

Schriftersetzung (siehe oben) — das wichtigste sichtbare Delta.
Kein $mode bei WriteHTML — übergib vollständiges HTML mit Inline-CSS.
Kein Format-Override pro AddPage — Größenänderungen erfolgen am Dokumentmodell.
Berechtigungen sind Reader-kooperativ (siehe Sicherheitshinweise).
Unabhängige Layout-Engine — Zeilenumbruch / Seitenumbruch unterscheiden sich bei dichtem Inhalt; erstellen Sie eine neue Baseline für visuelle Diffs.

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

Nicht unterstützt / keine direkte Entsprechung

mode-Konstruktor-String — nicht modelliert (immer Unicode).
format/orientation/Rand-Argumente pro AddPage() — keine Argumente in NextPDF.
mPDF-fontdata-Zuordnung — ersetzt durch Schriftverzeichnis + CSS-Abgleich.
Die Zielzeichen 'I'/'D'/'F'/'S' von mPDF — ersetzt durch das OutputDestination-Enum + save()/getPdfData().

Sichere Migrationsabfolge

Fügen Sie nextpdf/core neben mpdf/mpdf hinzu (behalten Sie mPDF vorerst).
Wählen Sie ein Dokument mit niedrigem Risiko aus. Konvertieren Sie new Mpdf([...]) über die Konfigurationszuordnung und WriteHTML/Output über die Verb-Zuordnung.
Registrieren Sie die Schriften, die das Dokument verwendet, in Config->fontsDirectory und fügen Sie explizite @font-face/family-Deklarationen für jeden mPDF-Alias hinzu.
Erzeugen Sie beide PDFs für dieselbe Eingabe; vergleichen Sie sie visuell. Unterschiede (Schriftersetzung, Zeilenumbruch) sind bei unabhängigen Engines zu erwarten — akzeptieren Sie sie pro Dokument.
Ordnen Sie jegliches Header/Footer-HTML dem Header/Footer-Mechanismus von NextPDF zu.
Wiederholen Sie das pro Dokument, beginnend mit dem niedrigsten Risiko; halten Sie mPDF bis zur letzten Umstellung installiert.
Entfernen Sie mpdf/mpdf nach der finalen Umstellung aus composer.json.

Die Migration testen

Erstellen Sie vor der Codeänderung Snapshots der mPDF-Ausgabe repräsentativer Dokumente (Golden Inputs; die Bytes werden sich unterscheiden).
Prüfen Sie jedes migrierte Dokument mit Ihrer eigenen Abnahmeprüfung (visueller Diff + Textextraktion). Das Schrift-/HTML-Verhalten von NextPDF wird durch examples/04-text-and-fonts.php und examples/08-html-basic.php sowie die Core-tests/-Html-/Font-Suites abgedeckt. Die Migrationsabnahme ist dokumentspezifisch und liegt in Ihrer Verantwortung.
Fügen Sie pro migriertem Dokument einen Regressionstest hinzu.

Nachweis / Nachverfolgbarkeit

Jede NextPDF-Verhaltensaussage auf dieser Seite ist durch einen Test, ein Beispiel, eine Quellsignatur oder einen ADR im Repository belegt — oder, sofern es sich um eine PDF-Formateigenschaft handelt, durch die im RAG verankerten ISO 32000-2- / CSS-Klauseln im Front-Matter-citations: und der Konformitätstabelle. mPDF-Verhalten wird nur als „unabhängige Engine — dokumentierte Unterschiede erwarten“ beschrieben; es wird keine Parität behauptet, die nicht durch ein Artefakt im Repository belegt ist.

NextPDF-Verhaltensaussage	Nachweis im Repository (Pfad)
`WriteHTML()` bildet direkt auf `Document::writeHtml(string $html): static` ab.	`src/Core/Concerns/HasTextOutput.php` (`writeHtml()`); `examples/08-html-basic.php`.
`WriteFixedPosHTML(...)` bildet auf `writeHtmlCell(...)` ab.	`src/Core/Concerns/HasTextOutput.php` (`writeHtmlCell()`).
`createStandalone()` erzeugt standardmäßig A4-Hochformat (`595.276 × 841.890 pt`).	`src/Core/Config.php` (Standard-`PageSize`); `tests/Unit/Core/DocumentCreateStandaloneAndConfigWithersEdgeCaseTest.php`.
`Margin`-Konstruktorreihenfolge ist `(top, right, bottom, left)`.	`src/ValueObjects/Margin.php` (Reihenfolge der promoted Properties).
Das Ausgabeziel ist das `NextPDF\Contracts\OutputDestination`-Enum; `'I'/'D'/'F'/'S'` werden nicht akzeptiert.	`src/Contracts/OutputDestination.php` (Fälle `Inline`/`Download`/`File`/`String`); `tests/Unit/Core/Concerns/DocumentOutputDestinationDispatchTest.php`.
`Output('','S')` → `getPdfData()`; `Output($path,'F')` → `save($path)`.	`src/Core/Concerns/HasOutput.php` (`getPdfData()`, `save()`, `output()`).
`SetProtection()` bildet auf `setEncryption(...)` ab; Berechtigungen sind reader-kooperativ.	`src/Core/Concerns/HasSecurity.php` (`setEncryption()`); ISO 32000-2 §14 (Front-Matter-`citations:`).
`SetTitle()` → `setTitle()`; Metadaten landen im Info-Dictionary / XMP.	`src/Core/Concerns/HasMetadata.php` (`setTitle()`); `tests/Unit/Core/Concerns/DocumentInfoMetadataSetterBaselineTest.php`; ISO 32000-2 §14 (Front-Matter-`citations:`).
Schriften werden immer als Teilmengenprogramme eingebettet.	`tests/Unit/Core/Concerns/DocumentTextOutputFontSubsettingAndBorderEdgeCaseTest.php`; `examples/04-text-and-fonts.php`; ISO 32000-2 §9 (Front-Matter-`citations:`).
Schriftabgleich / Fallback ist engine-spezifisch (Ersetzungs-Delta).	CSS Fonts 4 §5.5 (Front-Matter-`citations:` + Konformität).
`writeHtml()` arbeitet in einem Durchgang; der Spitzenspeicher folgt der Dokumentgröße.	`docs/architecture/adr/ADR-001-stream-based-rendering-pipeline.md`.

Rollback

Beide Pakete bleiben bis zur finalen Umstellung installiert; ein Rollback bedeutet daher pro Aufrufstelle, diese Aufrufstelle auf den mPDF-Pfad zurückzusetzen. Nach der finalen Umstellung bedeutet ein Rollback, mpdf/mpdf und den vorherigen Code aus der Versionsverwaltung wiederherzustellen. Es ist keine Datenmigration beteiligt.

Performance-Überlegungen

Siehe Performance. Das Single-Pass-Modell entfernt die Kosten des von mPDF gehaltenen Puffers. Die neuen Kosten pro Dokument entstehen durch die eager Schriftauflösung (Schritt 3), die sich über das Schriftverzeichnis cachen lässt.

Häufige Fallstricke

Den Schlüssel mode beibehalten und davon CJK-Verhalten erwarten (er wird weggelassen; CJK ist Schriftauswahl).
Beim Übergeben von WriteHTML($html, 2) (Nur-CSS-Modus) — binden Sie stattdessen CSS inline ein.
header/footer-HTML in den Body einfügen.
Für einen mPDF-Alias dieselbe Schrift erwarten, ohne eine explizite Familie.
byte-/pixelidentische Ausgabe erwarten (unabhängige Engines — diese Anleitung behauptet niemals einen Drop-in oder 100%ige Kompatibilität).
Die CSS-Unterstützungsmatrix nur als Empfehlung behandeln — sie ist die maßgebliche Quelle für „Verified“-Funktionen.