Migreren van mPDF naar NextPDF

In een oogopslag

Deze handleiding helpt u een mPDF-gebaseerde codebase over te zetten naar NextPDF core. In mPDF is de belangrijkste aanroep voor inhoud WriteHTML(), die rechtstreeks wordt toegewezen aan Document::writeHtml(). Het meeste werk zit in het toewijzen van de configuratiearray van de constructor (mPDF configureert alles via één associatieve array die wordt doorgegeven aan new Mpdf([...])) en in de verschillen in lettertypeverwerking. NextPDF en mPDF zijn onafhankelijke engines, dus een gemigreerd document is compatibel met de mPDF-uitvoer, niet byte-identiek eraan. Deze handleiding behandelt de toewijzing van API-werkwoorden, de toewijzing van de configuratiearray, verschillen in lettertypen, verschillen in ondersteuning voor Cascading Style Sheets (CSS), gedragsverschillen en een veilige volgorde.

De ondersteuningsmatrix voor Cascading Style Sheets (CSS) legt vast welke functies van Hypertext Markup Language (HTML) en CSS zijn geverifieerd. Deze handleiding beschrijft gedrag en claimt geen visuele gelijkwaardigheid met mPDF.

Installeren

composer require nextpdf/core:^3

Houd mpdf/mpdf geïnstalleerd tijdens de migratie. Verwijder het pas na de definitieve overstap (zie veilige migratievolgorde).

Conceptueel overzicht

Het Mpdf-object van mPDF combineert configuratie en rendering in één interface. Een constructorarray configureert het, en WriteHTML() plus de paginawerkwoorden (AddPage, SetHTMLHeader, SetHTMLFooter) sturen het aan. NextPDF brengt de configuratie onder in het onveranderlijke value object NextPDF\Core\Config en schrijft inhoud met Document::writeHtml(). De constructor heeft geen “mode”-string. NextPDF parseert de HTML die u doorgeeft en produceert het document daarna met save(), output() of getPdfData().

Lettertypen: mPDF wordt geleverd met een lettertypemap, een fontdata-toewijzing en een terugvalset met “core fonts”. NextPDF herleidt lettertypen uit één lettertypemap plus CSS font-family-overeenkomst en maakt altijd subsets van ingesloten lettertypen (International Organization for Standardization (ISO) 32000-2 §9, iso32000_2_sec9#x1.x45.p7). Lettertype-overeenkomst en terugval zijn engine-specifiek (CSS Fonts 4 §5.5, css_fonts_4#x1.x5.x5.x1.p13), dus glyphvervanging kan verschillen. Dit is het belangrijkste zichtbare verschil en wordt behandeld in het verschil in lettertypeverwerking.

API-oppervlak

De HTML-API van NextPDF is gedocumenteerd in de referentie van de Html-module. De belangrijkste toegangspunten zijn Document::createStandalone(), Document::writeHtml(string $html): static, Document::writeHtmlCell(...), Document::addPage(), Document::output(?string, OutputDestination), Document::save(string $path): void, Document::getPdfData(): string, en het value object NextPDF\Core\Config.

Toewijzing van API-werkwoorden

De openbare methodenamen van mPDF hieronder zijn geverifieerd aan de hand van de openbare upstream-repository (mpdf/mpdf, development); zie de in-repo herkomst-sidecar _source-sidecar-upstream-api.md. Er wordt geen upstream-documentatietekst gereproduceerd.

mPDF	NextPDF	Opmerkingen
`new Mpdf([...])`	`Document::createStandalone($config)`	De configuratiearray van mPDF wordt toegewezen aan `NextPDF\Core\Config`; zie configuratietoewijzing. Gebruik `DocumentFactory` voor langlevende workers.
`$mpdf->WriteHTML($html)`	`$doc->writeHtml($html)`	Directe toewijzing. Het tweede argument `$mode` van mPDF (volledig document vs. alleen CSS vs. element) heeft geen NextPDF-tegenhanger; geef volledige HTML door.
`$mpdf->WriteFixedPosHTML(...)`	`$doc->writeHtmlCell(...)`	Gepositioneerd HTML-gebied met opgegeven afmetingen; wijs de argumenten x/y/width/height toe.
`$mpdf->AddPage(...)`	`$doc->addPage()`	NextPDF accepteert de overschrijvingen per aanroep van mPDF voor orientation/format/marge niet als argumenten; wijzig daarom het documentmodel tussen aanroepen.
`$mpdf->SetHTMLHeader($html)` / `SetHTMLFooter($html)`	header/footer via de Layout-API	De doorlopende HTML-headers van mPDF worden toegewezen aan het NextPDF-mechanisme voor header/footer, niet aan inline HTML aan het begin van de body.
`$mpdf->Output($name, $dest)`	`$doc->output($name, OutputDestination::…)`	De bestemmingstekens van mPDF (`I`/`D`/`F`/`S`) worden toegewezen aan de enum `OutputDestination` (`Inline`/`Download`/file via `save()`/string via `getPdfData()`).
`$mpdf->Output('','S')`	`$doc->getPdfData()`	Retourneert bytes.
`$mpdf->Output($path,'F')`	`$doc->save($path)`	Schrijft naar een bestandspad.
`$mpdf->SetTitle($t)`	`$doc->setTitle($t)`	Komt terecht in het informatiewoordenboek / Extensible Metadata Platform (XMP) van ISO 32000-2 §14 (`iso32000_2_sec14#x1.x5.p5`).
`$mpdf->SetProtection($perms,...)`	`$doc->setEncryption(...)` (Security-API)	Permissies werken op basis van medewerking van de lezer, niet als toegangscontrole — zie Beveiligingsnotities.

Codevoorbeeld — snelstart

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

Codevoorbeeld — productie

Dit voorbeeld is afgestemd op examples/04-text-and-fonts.php, de uitvoerbare onderbouwing voor de lettertypeverwerkingsconcepten in deze handleiding. Het gebruikt een expliciet paginaformaat, marges en body-inhoud die lettertypeselectie test.

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

Randgevallen en valkuilen

Argument $mode op WriteHTML. WriteHTML($html, $mode) van mPDF (2 = alleen CSS, 1 = element) heeft geen equivalent. Neem CSS op in de HTML die u doorgeeft; er is geen volgorde van “eerst CSS schrijven, dan body schrijven”.
Overschrijvingen per AddPage. Met AddPage() kan mPDF midden in het document format/orientation via argumenten wijzigen. NextPDF addPage() neemt geen dergelijke argumenten; modelleer formaatwijzigingen via het document, niet via de pagina-aanroep.
Header/footer-HTML. mPDF registreert doorlopende headers als afzonderlijke HTML-fragmenten; plak ze niet in de body. Wijs ze toe aan het NextPDF-mechanisme voor header/footer.
Lettertypenamen. mPDF normaliseert lettertypenamen via zijn tabel fontdata/core-font. NextPDF matcht de CSS font-family tegen de lettertypemap; een mPDF-alias die stilzwijgend werd herleid, kan een expliciete @font-face/family nodig hebben.
Bestemmingstekens. 'I'/'D'/'F'/'S' worden niet geaccepteerd; gebruik de enum OutputDestination of save()/getPdfData().

Prestaties

writeHtml() verloopt in één doorloop (ADR-001); het piekgeheugen volgt de documentgrootte, niet een vastgehouden Document Object Model (DOM). Budget voor het voorbeeld in deze handleiding: wall_ms: 2000, peak_mb: 128. Splits bij lange documenten de inhoud over meerdere aanroepen van addPage() in plaats van één gigantische string door te geven. Dit is dezelfde richtlijn die geldt voor opdelen met $mode van mPDF, maar dan uitgedrukt via het paginamodel.

Beveiligingsnotities

Permissies werken op basis van medewerking van de lezer. SetProtection() → setEncryption() biedt vertrouwelijkheid, geen toegangscontrole: ISO-permissiebits zijn afhankelijk van een meewerkende lezer. Presenteer versleuteling niet als toegangscontrole aan gebruikers.
Metadata. SetTitle() en documentinformatie komen terecht in het informatiewoordenboek / XMP van ISO 32000-2 §14 (iso32000_2_sec14#x1.x5.p5); bewaar daar nooit geheimen.
NextPDF voert geen scripts in het document uit; geen enkele mPDF-directive verandert dat hier.

Conformiteit

Bewering	Specificatie	Clausule
Lettertypen worden geschreven als embedded/subset lettertypeprogramma’s.	ISO 32000-2	§9
Paginaformaat/marges worden toegewezen aan de paginagrensbox.	ISO 32000-2	§7
Titel- / beschermingsmetadata komen terecht in het informatiewoordenboek / XMP.	ISO 32000-2	§14
Lettertype-overeenkomst / terugval is engine-specifiek.	CSS Fonts 4	§5.5

NextPDF produceert ISO 32000-2-inhoud; het claimt geen visuele identiteit met mPDF. Beoordeel de uitvoer opnieuw wanneer u van renderer wisselt.

Commerciële context

Niet van toepassing. NextPDF core dekt het hier beschreven mPDF-migratiepad.

Zie ook

Migratiedetails (R6 vereiste secties)

Voor wie dit bedoeld is

Teams die mpdf/mpdf gebruiken voor server-side HTML-naar-PDF. Als uw code is opgebouwd rond new Mpdf([...]) + WriteHTML + Output (+ optionele header/footer), dan wordt dit afgedekt door de werkwoordtoewijzing en configuratietoewijzing.

Reikwijdte

In scope: de configuratiearray van de Mpdf-constructor, WriteHTML/Output/AddPage, headers/footers, lettertypen, bescherming, metadata. Buiten scope: interne mPDF-klassen en het API-oppervlak voor hulpmiddelen zoals Quick Response (QR)/barcode/watermark. Wijs die toe aan de bijbehorende NextPDF-modules — Barcode, Graphics — die hier niet worden behandeld.

Compatibiliteitstoewijzing

Gedragscompatibiliteit, geen drop-in shim: NextPDF biedt geen klasse-shim voor Mpdf. Herschrijf elke aanroepplek. Gebruik de geverifieerde rijen van de CSS-ondersteuningsmatrix voor verwachtingen over CSS-functies.

Toewijzing van de configuratiearray van de constructor

De mPDF-configuratiesleutels hieronder zijn geverifieerd aan de hand van de openbare upstream-repository (mpdf/mpdf, development). Er wordt geen upstream-documentatietekst gereproduceerd.

mPDF-configuratiesleutel	NextPDF	Opmerkingen
`mode`	(geen equivalent)	De mode-string van mPDF (`'utf-8'`, `'c'`, `'+aCJK'`, …) selecteert font/script-gedrag. NextPDF is altijd Unicode; Chinese, Japanese, and Korean (CJK)-tekst wordt afgehandeld via lettertypeselectie, niet via een mode. Laat de sleutel weg.
`format`	`Config->pageSize` (value object (VO) `PageSize`)	Benoemde formaten worden expliciete puntafmetingen; arrays `[w,h]` worden toegewezen aan een `PageSize`.
`orientation`	verwissel width/height van `PageSize`	Geen oriëntatievlag; landschap betekent width > height.
`default_font_size`	CSS-basislettergrootte	Stel dit in uw basisstylesheet in, niet via een constructorsleutel.
`default_font`	CSS `font-family` / geregistreerd lettertype	Stel de standaardfamilie in via CSS / lettertyperegistratie.
`margin_left` / `margin_right` / `margin_top` / `margin_bottom`	`Config->margins` (`Margin` VO) in punten	Gebruik één value object `Margin`; de constructorvolgorde is `Margin(top, right, bottom, left)` (verifieer aan de hand van `src/ValueObjects/Margin.php`), niet de sleutelvolgorde van mPDF.
`margin_header` / `margin_footer`	header/footer-offset via de Layout-API	Wijs deze toe aan de NextPDF-configuratie voor header/footer, niet aan constructorsleutels.

Verschil in lettertypeverwerking

Eén lettertypemap. De lettertypemaplijst, fontdata-toewijzing en core-font-terugval van mPDF komen in NextPDF samen in Config->fontsDirectory plus CSS font-family-overeenkomst.
Maakt altijd subsets. NextPDF maakt altijd subsets van ingesloten lettertypen (ISO 32000-2 §9, iso32000_2_sec9#x1.x45.p7); de subset-flags van mPDF hebben geen equivalent en zijn niet nodig.
Overeenkomst is engine-specifiek. Lettertype-overeenkomst en terugval verschillen per engine (CSS Fonts 4 §5.5, css_fonts_4#x1.x5.x5.x1.p13); een mPDF-lettertypealias kan een expliciete @font-face of exacte familienaam nodig hebben. Leg de glyph-weergave na de migratie opnieuw vast als baseline. Vervangingsverschillen zijn verwacht gedrag, geen defecten.

Gedragsverschillen

Lettertypevervanging (zie hierboven) — het belangrijkste zichtbare verschil.
Geen $mode op WriteHTML — geef volledige HTML met inline CSS door.
Geen format-overschrijving per AddPage — modelleer formaatwijzigingen via het document.
Permissies werken op basis van medewerking van de lezer (zie Beveiligingsnotities).
Onafhankelijke layout-engine — regelafbreking / paginering verschilt bij dichte inhoud; stel visuele diffs opnieuw als baseline in.

Dit zijn gedocumenteerde gedragsverschillen, geen defecten in een van beide engines.

Niet ondersteund / geen direct equivalent

mode-constructorstring — niet gemodelleerd (altijd Unicode).
AddPage()-argumenten per pagina voor format/orientation/marge — geen argumenten in NextPDF.
mPDF fontdata-toewijzing — vervangen door lettertypemap + CSS-overeenkomst.
De bestemmingstekens 'I'/'D'/'F'/'S' van mPDF — vervangen door de enum OutputDestination + save()/getPdfData().

Veilige migratievolgorde

Voeg nextpdf/core toe naast mpdf/mpdf; houd mPDF voorlopig geïnstalleerd.
Kies één document met een laag risico. Converteer new Mpdf([...]) via de configuratietoewijzing en WriteHTML/Output via de werkwoordtoewijzing.
Registreer de lettertypen die het document gebruikt in Config->fontsDirectory en voeg expliciete @font-face/family-declaraties toe voor elke mPDF-alias.
Genereer beide PDF’s voor dezelfde invoer en vergelijk ze visueel. Verschillen (lettertypevervanging, regelafbreking) zijn te verwachten voor onafhankelijke engines — accepteer ze per document.
Wijs alle header/footer-HTML toe aan het NextPDF-mechanisme voor header/footer.
Herhaal per document, het laagste risico eerst; houd mPDF geïnstalleerd tot de laatste overstap.
Verwijder mpdf/mpdf uit composer.json na de definitieve overstap.

De migratie testen

Maak een snapshot van de mPDF-uitvoer voor representatieve documenten voordat u code wijzigt (golden inputs; de bytes zullen verschillen).
Bepaal voor elk gemigreerd document de acceptatie met uw eigen controle (visuele diff
- tekstextractie). Het lettertype-/HTML-gedrag van NextPDF wordt getest door examples/04-text-and-fonts.php en examples/08-html-basic.php plus de core tests/ Html-/Font-suites. De acceptatie van de migratie is documentspecifiek en blijft uw verantwoordelijkheid.
Voeg per gemigreerd document een regressietest toe.

Bewijs / traceerbaarheid

Elke gedragsbewering van NextPDF op deze pagina wordt onderbouwd door een in-repo test, voorbeeld, bronhandtekening of architecture decision record (ADR), of, voor PDF-formaateigenschappen, door de retrieval-augmented generation (RAG)-vastgepinde ISO 32000-2- / CSS-clausules in de frontmatter citations: en de Conformiteit-tabel. mPDF-gedrag wordt alleen beschreven als “onafhankelijke engine — verwacht gedocumenteerde verschillen”; deze pagina claimt geen pariteit die niet door een in-repo artefact wordt bewezen.

NextPDF-gedragsbewering	In-repo bewijs (pad)
`WriteHTML()` wordt rechtstreeks toegewezen aan `Document::writeHtml(string $html): static`.	`src/Core/Concerns/HasTextOutput.php` (`writeHtml()`); `examples/08-html-basic.php`.
`WriteFixedPosHTML(...)` wordt toegewezen aan `writeHtmlCell(...)`.	`src/Core/Concerns/HasTextOutput.php` (`writeHtmlCell()`).
`createStandalone()` is standaard A4 staand (`595.276 × 841.890 pt`).	`src/Core/Config.php` (standaard `PageSize`); `tests/Unit/Core/DocumentCreateStandaloneAndConfigWithersEdgeCaseTest.php`.
`Margin`-constructorvolgorde is `(top, right, bottom, left)`.	`src/ValueObjects/Margin.php` (volgorde van gepromote eigenschappen).
De uitvoerbestemming is de enum `NextPDF\Contracts\OutputDestination`; `'I'/'D'/'F'/'S'` worden niet geaccepteerd.	`src/Contracts/OutputDestination.php` (cases `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()` wordt toegewezen aan `setEncryption(...)`; permissies werken op basis van medewerking van de lezer.	`src/Core/Concerns/HasSecurity.php` (`setEncryption()`); ISO 32000-2 §14 (frontmatter `citations:`).
`SetTitle()` → `setTitle()`; metadata komt terecht in het informatiewoordenboek / XMP.	`src/Core/Concerns/HasMetadata.php` (`setTitle()`); `tests/Unit/Core/Concerns/DocumentInfoMetadataSetterBaselineTest.php`; ISO 32000-2 §14 (frontmatter `citations:`).
Lettertypen worden altijd ingesloten als subset-programma’s.	`tests/Unit/Core/Concerns/DocumentTextOutputFontSubsettingAndBorderEdgeCaseTest.php`; `examples/04-text-and-fonts.php`; ISO 32000-2 §9 (frontmatter `citations:`).
Lettertype-overeenkomst / terugval is engine-specifiek (vervangingsverschil).	CSS Fonts 4 §5.5 (frontmatter `citations:` + Conformiteit).
`writeHtml()` verloopt in één doorloop; het piekgeheugen volgt de documentgrootte.	`docs/architecture/adr/ADR-001-stream-based-rendering-pipeline.md`.

Terugdraaien

Beide pakketten blijven geïnstalleerd tot de definitieve overstap, dus terugdraaien per aanroepplek betekent dat u die aanroepplek terugzet naar het mPDF-pad. Na de definitieve overstap betekent terugdraaien dat u mpdf/mpdf en de eerdere code uit versiebeheer herstelt. Er is geen gegevensmigratie bij betrokken.

Prestatieoverwegingen

Zie Prestaties. Het model met één doorloop vermijdt de kosten van de door mPDF vastgehouden buffer. De nieuwe kosten per document zitten in de eager herleiding van lettertypen (stap 3), die via de lettertypemap te cachen is.

Veelvoorkomende valkuilen

De sleutel mode behouden en daar CJK-gedrag van verwachten; NextPDF laat hem vallen, en CJK draait om lettertypeselectie.
WriteHTML($html, 2) doorgeven (alleen-CSS-mode); gebruik in plaats daarvan inline CSS.
header/footer-HTML in de body plakken.
Verwachten dat een mPDF-alias zonder expliciete familie naar hetzelfde lettertype wordt herleid.
byte/pixel-identical uitvoer verwachten (onafhankelijke engines — deze handleiding claimt nooit een drop-in of 100% compatibiliteit).
De CSS-ondersteuningsmatrix als adviserend behandelen; die is de autoriteit voor geverifieerde functies.