Migreren van Dompdf naar NextPDF

In het kort

Deze handleiding helpt u bij het migreren van een op Dompdf gebaseerde codebase die Portable Document Format (PDF)-bestanden genereert uit Hypertext Markup Language (HTML) naar de NextPDF Html-pipeline. De meeste aanroeppunten kunt u mechanisch omzetten, omdat beide bibliotheken dezelfde globale stroom volgen: HTML laden, weergeven en een PDF uitvoeren. Het echte werk zit in de toewijzingstabel voor opties en de verschillen in ondersteuning voor Cascading Style Sheets (CSS). NextPDF en Dompdf zijn onafhankelijke engines, dus een lay-out die Dompdf heeft geproduceerd is compatibel met het NextPDF-resultaat, maar er niet byte-identiek aan. Deze handleiding behandelt werkwoordtoewijzing, toewijzing van optiesleutels, gedragsverschillen en een veilige migratievolgorde.

Ondersteuning in NextPDF voor een HTML/CSS-functie garandeert niet dat een Dompdf-document pixel-voor-pixel wordt gereproduceerd. De CSS-ondersteuningsmatrix is de autoriteit voor geverifieerde functies. Deze handleiding beschrijft gedrag en claimt geen visuele gelijkwaardigheid.

Installatie

composer require nextpdf/core:^3

Houd dompdf/dompdf geïnstalleerd tijdens de overgang. In de veilige migratievolgorde draaien beide engines naast elkaar totdat elk aanroeppunt is omgezet. Verwijder het pakket zodra de omzetting is voltooid.

Conceptueel overzicht

Het Dompdf-object van Dompdf is één facade die het Document Object Model (DOM), de stylesheet, de frameboom en het canvas beheert. NextPDF splitst deze verantwoordelijkheden: een NextPDF\Core\Document beheert het paginamodel en de uitvoer, en writeHtml() stuurt de HTML-pipeline aan. Er is geen aparte tweestapsfase voor “weergeven en daarna uitvoeren”. writeHtml() bouwt de inhoud op terwijl het schrijft, en u voert het document uit met save(), output() of getPdfData().

De pagina-inhoud die NextPDF schrijft, is contentstreampainting volgens ISO 32000-2 (ISO 32000-2 §8, iso32000_2_sec8#x1.x3.p14). De paginageometrie die de papierformaatoptie regelt, wordt toegewezen aan de MediaBox van het pagina-object (ISO 32000-2 §7, iso32000_2_sec7#x1.x104.p10). Dit zijn enginefundamenten die elke conforme writer gemeen heeft. Het lay-outalgoritme dat CSS omzet in die inhoud, is dat van NextPDF zelf, en het verschilt van dat van Dompdf; zie Gedragsverschillen.

API-oppervlak

De NextPDF Html-applicatieprogrammeerinterface (API) is gedocumenteerd in de referentie van de Html-module, die automatisch wordt gegenereerd uit PHPDoc. De hieronder gebruikte ingangspunten zijn Document::createStandalone(), Document::writeHtml(string $html): static, Document::writeHtmlCell(...), Document::output(?string, OutputDestination), Document::save(string $path): void, Document::getPdfData(): string, en het waardeobject NextPDF\Core\Config (pageSize, margins, fontsDirectory).

API-werkwoordtoewijzing

De onderstaande namen van de publieke Dompdf-API zijn geverifieerd tegen de publieke upstream-repository (dompdf/dompdf, master); zie de provenance-sidecar _source-sidecar-upstream-api.md in de repository. Er wordt geen upstream-documentatietekst gereproduceerd.

Dompdf	NextPDF	Opmerkingen
new Dompdf($options)	Document::createStandalone($config)	Dompdf verwacht een Options-object; NextPDF verwacht een NextPDF\Core\Config. Gebruik DocumentFactory voor langlevende workers in plaats van createStandalone().
$dompdf->loadHtml($html, $encoding)	$doc->writeHtml($html)	NextPDF behandelt invoer als UTF-8. Codeer niet-UTF-8-invoer vóór de aanroep opnieuw in plaats van een coderingsargument door te geven.
$dompdf->loadHtmlFile($file)	$doc->writeHtml(file_get_contents($file))	NextPDF heeft geen variant voor het laden van bestanden. Lees het bestand zelf, zodat het resourcebeleid in uw eigen code blijft.
$dompdf->setPaper($size, $orientation)	ConfigpageSize (een PageSize-waarde-object)	Zie de toewijzingstabel voor opties.
$dompdf->render()	(impliciet)	NextPDF bouwt de lay-out op tijdens writeHtml(); er is geen aparte weergavefase. Verwijder de aanroep van render().
$dompdf->output()	$doc->getPdfData()	Retourneert de PDF-bytes.
$dompdf->stream($name, $opts)	$doc->output($name, OutputDestination::Download)	NextPDF selecteert de bestemming met de OutputDestination-enum.
$dompdf->setBasePath($p) / setProtocol() / setBaseHost()	(resourceresolutie verschilt)	NextPDF resolveert relatieve resources tegen de werkset van het document, niet tegen een basistriplet van path/protocol; zie Gedragsverschillen.
$dompdf->addInfo($label, $value)	$doc->setTitle() / setAuthor() / metadata-API	De vrijevorm-infoparen van Dompdf worden toegewezen aan getypeerde metadata-setters (ISO 32000-2 §14 documentinformatie, iso32000_2_sec14#x1.x5.p5).
$dompdf->setHttpContext($ctx)	(geen equivalent)	NextPDF haalt geen externe resources op via een streamcontext; zie Niet ondersteund / geen direct equivalent.

Codevoorbeeld — Snelstart

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

Codevoorbeeld — Productie

Dit weerspiegelt examples/08-html-basic.php, de uitvoerbare basis voor deze handleiding, met expliciete marges en een afwijkend papierformaat. Het komt overeen met een Dompdf-aanroep van setPaper() plus een margeconfiguratie via 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);">

Randgevallen & valkuilen

• Geen tweefasige weergave. Dompdf-code die de status inspecteert tussen render() en output(), zoals het uitlezen van het aantal pagina’s, heeft op die exacte grens geen NextPDF-tegenhanger. Vraag het document in plaats daarvan na writeHtml() op.
• Codering. NextPDF laat de $encoding-parameter van Dompdf weg. Converteer invoer naar UTF-8 vóór writeHtml(). Het doorgeven van Latin-1-bytes levert mojibake op, geen fout.
• render() blijft staan. Een achtergebleven aanroep in de stijl van $dompdf->render() heeft geen NextPDF-methode en faalt met een fatale “undefined method”-fout. Verwijder de aanroep tijdens de omzetting; stub deze niet.
• Inline-PHP. De Dompdf-optie enable_php evalueert <script type="text/php">. NextPDF voert geen PHP uit binnen het document, naar ontwerp, omdat dit een injectievlak is. Verplaats die logica naar uw PHP-code vóór writeHtml().
• Resolutie van relatieve resources. Dompdf resolveert <img src> tegen het basistriplet van path/protocol/host. NextPDF resolveert tegen de werkset van het document. Geef tijdens de migratie absolute paden of vooraf geresolveerde data-URI’s door om die variabele te elimineren.

Prestaties

writeHtml() bouwt de lay-out op in één streamingdoorloop, zoals beschreven in architectuurbeslissingsrecord ADR-001. Er wordt na de lay-out geen tussenliggend frameboomobject vastgehouden, dus het piekgeheugen volgt de documentgrootte in plaats van het aantal DOM-knooppunten. Het prestatiebudget voor het voorbeeld in deze handleiding is wall_ms: 2000, peak_mb: 128. Splits voor grote documenten de HTML over addPage()-grenzen in plaats van één string van meerdere megabytes op te bouwen.

Beveiligingsnotities

• Geen extern ophalen via streamcontext. NextPDF implementeert Dompdf’s pad voor extern ophalen via setHttpContext() / enable_remote niet. Resolveer en valideer externe assets in uw applicatie en geef vervolgens bytes of data-URI’s door. Dit elimineert het server-side request forgery (SSRF)-aanvalsoppervlak dat enable_remote met zich meebrengt.
• Geen code-uitvoering binnen het document. Het ontbreken van een equivalent voor enable_php is bewuste hardening, geen tekortkoming.
• Documentmetadata die u via de getypeerde setters instelt, wordt geschreven naar de ISO 32000-2 §14 informatiedictionary / het Extensible Metadata Platform (XMP) (iso32000_2_sec14#x1.x5.p5). Zet daar geen geheimen in.

Conformiteit

Verklaring	Specificatie	Clausule	reference_id
Pagina-inhoud is contentstreampainting in het opaque/transparent-model.	ISO 32000-2	§8
Papierformaat wordt toegewezen aan het begrenzingsvak van het pagina-object.	ISO 32000-2	§7
HTML-lettertypen worden geschreven als embedded/subset-lettertypeprogramma’s.	ISO 32000-2	§9
De verwerking van witruimte / regelafbreking is engine-specifiek.	CSS Text 3	§6.5

NextPDF produceert ISO 32000-2-inhoud. Het claimt niet dat een gemigreerd Dompdf-document visueel identiek is. Beoordeel de uitvoer telkens opnieuw wanneer u van renderer wisselt.

Commerciële context

Niet van toepassing. Core dekt dit HTML-naar-PDF-migratiepad.

Zie ook

• Migratie-index
• Migreren van mPDF
• CSS-ondersteuningsmatrix
• Html-module

---

Migratiedetails (R6 vereiste secties)

Voor wie dit bedoeld is

Gebruik dit als uw team dompdf/dompdf gebruikt voor server-side HTML-naar-PDF en de NextPDF-engine wil gebruiken. Als u alleen loadHtml / setPaper / render / output aanroept, dekt de werkwoordtoewijzing uw volledige API-oppervlak.

Reikwijdte

Binnen de reikwijdte vallen de facade-werkwoorden van Dompdf, de Options-sleutels, verwachtingen over CSS-functiepariteit, resourceresolutie en metadata. Buiten de reikwijdte vallen de interne FrameTree/Canvas/Stylesheet-objecten van Dompdf. NextPDF heeft hiervoor geen publieke equivalenten, dus migreer geen code die deze rechtstreeks benadert; vervang die door de publieke API.

Compatibiliteitstabel

Dekking betekent gedragscompatibiliteit, geen drop-in-shim. NextPDF heeft geen Dompdf-class-shim (in tegenstelling tot het TCPDF-pad; zie /migration/tcpdf-compat/). Herschrijf elk aanroeppunt met de werkwoordtoewijzing. De geverifieerde rijen van de CSS-ondersteuningsmatrix bepalen de verwachtingen over CSS-functies volledig. Deze handleiding herhaalt de status per eigenschap niet.

Toewijzingstabel voor opties en configuratie

Dompdf-optie (sleutel / setter)	NextPDF	Opmerkingen
default_paper_size / setDefaultPaperSize() ; setPaper($size,...)	Config->pageSize (PageSize-VO)	Benoemde formaten worden expliciete puntafmetingen. new PageSize(595.276, 841.890, 'A4') is de standaard van createStandalone().
default_paper_orientation / setDefaultPaperOrientation()	verwissel PageSize width/height	NextPDF heeft geen oriëntatievlag. Een liggende pagina is een PageSize met breedte > hoogte.
dpi / setDpi()	(geen globale instelling)	NextPDF werkt in PDF-punten (1/72 inch). Afbeeldingsformaat wordt per afbeelding bepaald, niet via een documentbrede vermenigvuldiger van dots per inch (DPI). Herbereken vaste pixelformaten naar punten.
enable_remote / setIsRemoteEnabled()	(geen equivalent — naar ontwerp)	Resolveer externe assets in uw code; zie Beveiligingsnotities.
enable_html5_parser / setIsHtml5ParserEnabled()	(parseert altijd HTML)	Geen schakelaar; de parser is de pipeline.
enable_php / setIsPhpEnabled()	(geen equivalent — naar ontwerp)	PHP binnen het document wordt niet ondersteund. Verplaats logica uit het sjabloon.
font_dir / setFontDir()	Config->fontsDirectory	Eén enkele string voor de lettertypemap.
chroot	(resolveer in de applicatie)	NextPDF accepteert geen optie voor een bestandssysteem-jail. Valideer paden voordat u bytes doorgeeft.
default_font / setDefaultFont()	CSS font-family / geregistreerd lettertype	Stel de standaard in uw basisstylesheet of lettertyperegistratie in, niet via een globale optie.
enable_font_subsetting / setIsFontSubsettingEnabled()	(maakt altijd een subset)	NextPDF maakt altijd een subset van ingebedde lettertypen (ISO 32000-2 §9, iso32000_2_sec9#x1.x45.p7). Er is geen “uit”; een Dompdf-pad met de vlag uit heeft geen equivalent en is niet nodig.

Gedragsverschillen

• Lay-outengine. Dompdf en NextPDF gebruiken onafhankelijke CSS-lay-outimplementaties. Het samenvouwen van witruimte en het afbreken van regels zijn gespecificeerd, maar blijven enginegevoelig (CSS Text 3 §6.5, css_text_3#x1.x6.x5.p20). Verwacht verschillen in regelafbreking en paginering bij dichte tekst. Leg visuele diffs na de migratie opnieuw vast als basislijn.
• Rendergrens. Geen tweefasige grens van render()/output() (zie Randgevallen).
• Resourceresolutie. De verwerking van basispad/protocol/host verschilt van de werkset van het document.
• DPI-model. PDF-punten verschillen van de DPI-vermenigvuldiger van Dompdf.
• Metadata. Vrijevorm-addInfo()-paren verschillen van getypeerde setters (ISO 32000-2 §14, iso32000_2_sec14#x1.x5.p5).

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

Niet ondersteund / geen direct equivalent

• enable_php (PHP binnen het document) — bewust afwezig.
• setHttpContext() / enable_remote externe ophaling — bewust afwezig.
• Publieke toegang tot FrameTree / Canvas / Stylesheet — geen publiek equivalent.
• dpi als document-globale vermenigvuldiger — niet gemodelleerd.

Code die hiervan afhankelijk is, “migreert” niet. Verwijder die code of formuleer die opnieuw als applicatiecode op basis van de bovenstaande rijen.

Veilige migratievolgorde

1. Voeg nextpdf/core toe naast dompdf/dompdf. Verwijder Dompdf nog niet.
2. Kies één document met een laag risico. Herschrijf het aanroeppunt met de werkwoordtoewijzing en verwijder de aanroep van render().
3. Genereer beide PDF’s uit dezelfde invoer en vergelijk ze visueel. Beschouw verschillen als te verwachten omdat de engines onafhankelijk zijn, en bepaal de acceptatie per document.
4. Zet het optiegebruik om met de toewijzingstabel voor opties; herbereken uit DPI afgeleide formaten naar punten.
5. Resolveer externe en relatieve assets vooraf naar absolute paden of data-URI’s om de resolutievariabele te elimineren.
6. Herhaal dit per document, van het laagste risico naar het hoogste. Houd beide engines geïnstalleerd totdat het laatste aanroeppunt is omgezet.
7. Verwijder dompdf/dompdf pas uit composer.json na de laatste omzetting.

De migratie testen

• Maak een snapshot van de Dompdf-uitvoer van representatieve documenten voordat u code wijzigt. Gebruik gouden invoer, geen gouden bytes, omdat de bytes zullen verschillen.
• Laat voor elk gemigreerd document de NextPDF-uitvoer door uw eigen acceptatiecontrole lopen, zoals een visuele diff of assertions voor tekstextractie. Het gedrag van de eigen HTML-pipeline van NextPDF wordt gedekt door examples/08-html-basic.php en de core tests/ Html-suite. Migratieacceptatie is documentspecifiek, en u bent verantwoordelijk voor het asserteren ervan.
• Voeg voor elk gemigreerd document een regressietest toe, zodat een toekomstige engine-update wordt gedetecteerd.

Bewijs / traceerbaarheid

Elke gedragsverklaring over NextPDF op deze pagina wordt ondersteund door een test, voorbeeld, bronsignatuur of architectuurbeslissingsrecord (ADR) in de repository, of, voor PDF-formaateigenschappen, door de met Retrieval-Augmented Generation (RAG) vastgepinde ISO 32000-2 / CSS-clausules in de frontmatter citations: en de Conformiteit-tabel. Dompdf-gedrag wordt alleen geassert als “onafhankelijke engine — verwacht gedocumenteerde verschillen”. Deze pagina claimt geen pariteit tenzij een artefact in de repository dit bewijst.

Gedragsclaim over NextPDF	Bewijs in de repository (pad)
De standaardpagina van createStandalone() is A4 staand (595.276 × 841.890 pt).	src/Core/Config.php (default PageSize(595.276, 841.890, 'A4')); tests/Unit/Core/DocumentCreateStandaloneAndConfigWithersEdgeCaseTest.php (createStandaloneWithNullConfigBuildsDocumentWithA4Defaults).
writeHtml() bouwt de lay-out op in één streaming-doorloop; geen behouden DOM na de lay-out.	docs/architecture/adr/ADR-001-stream-based-rendering-pipeline.md; src/Core/Concerns/HasTextOutput.php (writeHtml()).
writeHtml() maakt automatisch de eerste pagina aan wanneer er geen bestaat.	tests/Unit/Core/Concerns/DocumentTextOutputFontSubsettingAndBorderEdgeCaseTest.php (writeHtmlAutoCreatesFirstPageWhenNoPagesExist).
output() / save() / getPdfData() zijn de uitvoerwerkwoorden (geen tweefasig render/output).	src/Core/Concerns/HasOutput.php (output(), save(), getPdfData()); tests/Unit/Core/Concerns/DocumentOutputDestinationDispatchTest.php.
De uitvoerbestemming is de NextPDF\Contracts\OutputDestination-enum (Inline/Download/File/String).	src/Contracts/OutputDestination.php; tests/Unit/Core/Concerns/DocumentOutputDestinationDispatchTest.php.
HTML-lettertypen worden altijd geschreven als embedded/subset-programma’s.	tests/Unit/Core/Concerns/DocumentTextOutputFontSubsettingAndBorderEdgeCaseTest.php (recordUsedCharactersAffectsFontSubsetting); ISO 32000-2 §9 (front-matter citations:).
Getypeerde metadata-setters (setTitle/setAuthor) vervangen de vrijevorm-addInfo().	src/Core/Concerns/HasMetadata.php (setTitle(), setAuthor()); tests/Unit/Core/Concerns/DocumentInfoMetadataSetterBaselineTest.php.
Volledige HTML-pipeline van begin tot eind (de uitvoerbare basis van deze handleiding).	examples/08-html-basic.php; core tests/Unit/Html/ suite.
Witruimte / regelafbreking is engine-specifiek (lay-outdelta).	CSS Text 3 §6.5 (front-matter citations: + Conformance).

Terugdraaien

Omdat beide pakketten geïnstalleerd blijven tot de laatste omzetting, betekent terugdraaien voor een niet-omgezet aanroeppunt dat u dat aanroeppunt terugzet naar het Dompdf-pad. Na de laatste omzetting betekent terugdraaien dat u dompdf/dompdf en het vorige aanroeppunt herstelt vanuit versiebeheer. Er is geen datamigratie bij betrokken; alleen codewijzigingen.

Prestatieoverwegingen

Zie Prestaties. Het eenmalige doorloopmodel betekent dat de migratie geen kosten introduceert voor het vasthouden van de frameboom. De belangrijkste wijziging in kosten per document is de vooraf uitgevoerde assetresolutie uit stap 5, die u kunt cachen.

Veelvoorkomende valkuilen

• render() laten staan, wat een fatale undefined-method-fout veroorzaakt.
• Niet-UTF-8-bytes doorgeven na het weglaten van $encoding, wat stille mojibake veroorzaakt.
• Byte-identieke of pixel-identieke uitvoer verwachten van onafhankelijke engines. Deze handleiding claimt nooit een drop-in of 100% compatibiliteit.
• Vertrouwen op enable_php-sjablonen, die u moet herstructureren zodat die afhankelijkheid verdwijnt.
• De CSS-ondersteuningsmatrix als adviserend beschouwen. Het is de autoriteit voor geverifieerde functies en voor uw verwachtingen.