Migrasi dari Dompdf ke NextPDF

Sekilas

Panduan ini membantu Anda memindahkan basis kode yang menggunakan Dompdf untuk menghasilkan berkas Portable Document Format (PDF) dari Hypertext Markup Language (HTML) ke pipeline Html NextPDF. Sebagian besar lokasi pemanggilan dapat diterjemahkan secara mekanis karena kedua pustaka mengikuti alur umum yang sama: memuat HTML, merendernya, dan menghasilkan PDF. Bagian utama pekerjaannya adalah pemetaan opsi dan perbedaan dukungan Cascading Style Sheets (CSS). NextPDF dan Dompdf merupakan mesin independen, sehingga tata letak yang dihasilkan Dompdf bersifat kompatibel dengan hasil NextPDF, bukan identik byte demi byte. Panduan ini mencakup pemetaan verba, pemetaan kunci opsi, perbedaan perilaku, dan urutan migrasi yang aman.

Dukungan NextPDF untuk suatu fitur HTML/CSS tidak menjamin bahwa dokumen Dompdf akan direproduksi piksel demi piksel. Matriks dukungan CSS adalah acuan otoritatif untuk fitur yang berstatus Terverifikasi. Panduan ini menjelaskan perilaku; panduan ini tidak mengklaim kesetaraan visual.

Pemasangan

composer require nextpdf/core:^3

Pertahankan dompdf/dompdf tetap terpasang selama masa transisi. Urutan migrasi yang aman menjalankan kedua mesin secara berdampingan hingga setiap lokasi pemanggilan dialihkan. Hapus paket tersebut setelah proses peralihan selesai.

Tinjauan konseptual

Objek Dompdf milik Dompdf adalah satu fasad tunggal yang menaungi Document Object Model (DOM), lembar gaya, pohon frame, dan kanvas. NextPDF memisahkan tanggung jawab tersebut: sebuah NextPDF\Core\Document memiliki model halaman dan output, sedangkan writeHtml() menjalankan pipeline HTML. Tidak ada fase dua langkah “render, lalu output” yang terpisah. writeHtml() menata konten saat menuliskannya, dan Anda menghasilkan dokumen dengan save(), output(), atau getPdfData().

Konten halaman yang ditulis NextPDF adalah representasi aliran konten ISO 32000-2 (ISO 32000-2 §8, iso32000_2_sec8#x1.x3.p14). Geometri halaman yang dikendalikan oleh opsi ukuran kertas dipetakan ke objek halaman MediaBox (ISO 32000-2 §7, iso32000_2_sec7#x1.x104.p10). Ini adalah landasan mesin yang digunakan bersama oleh setiap writer yang konforman. Algoritme tata letak yang mengubah CSS menjadi konten tersebut adalah milik NextPDF sendiri, dan berbeda dari milik Dompdf; lihat Perbedaan perilaku.

Permukaan API

Application programming interface (API) Html NextPDF didokumentasikan dalam referensi modul Html, yang dihasilkan otomatis dari PHPDoc. Titik masuk yang digunakan di bawah ini adalah Document::createStandalone(), Document::writeHtml(string $html): static, Document::writeHtmlCell(...), Document::output(?string, OutputDestination), Document::save(string $path): void, Document::getPdfData(): string, dan objek nilai NextPDF\Core\Config (pageSize, margins, fontsDirectory).

Pemetaan verba API

Nama-nama API publik Dompdf di bawah ini telah dikonfirmasi terhadap repositori publik upstream (dompdf/dompdf, master); lihat sidecar provenance _source-sidecar-upstream-api.md di dalam repo. Tidak ada teks dokumentasi upstream yang direproduksi.

Dompdf	NextPDF	Catatan
new Dompdf($options)	Document::createStandalone($config)	Dompdf menerima objek Options; NextPDF menerima NextPDF\Core\Config. Gunakan DocumentFactory untuk worker yang berumur panjang, bukan createStandalone().
$dompdf->loadHtml($html, $encoding)	$doc->writeHtml($html)	NextPDF memperlakukan input sebagai UTF-8. Transkode input non-UTF-8 sebelum pemanggilan, bukan meneruskan argumen pengodean.
$dompdf->loadHtmlFile($file)	$doc->writeHtml(file_get_contents($file))	NextPDF tidak memiliki varian untuk memuat berkas. Baca berkas sendiri agar kebijakan sumber daya tetap berada di kode Anda.
$dompdf->setPaper($size, $orientation)	ConfigpageSize (objek nilai PageSize)	Lihat peta opsi.
$dompdf->render()	(implisit)	NextPDF melakukan tata letak selama writeHtml(); tidak ada fase render yang terpisah. Hapus pemanggilan render().
$dompdf->output()	$doc->getPdfData()	Mengembalikan byte PDF.
$dompdf->stream($name, $opts)	$doc->output($name, OutputDestination::Download)	NextPDF memilih tujuan dengan enum OutputDestination.
$dompdf->setBasePath($p) / setProtocol() / setBaseHost()	(resolusi sumber daya berbeda)	NextPDF meresolusi sumber daya relatif terhadap working set dokumen, bukan triplet path/protocol dasar; lihat Perbedaan perilaku.
$dompdf->addInfo($label, $value)	$doc->setTitle() / setAuthor() / API metadata	Pasangan info format bebas milik Dompdf dipetakan ke setter metadata bertipe (ISO 32000-2 §14 informasi dokumen, iso32000_2_sec14#x1.x5.p5).
$dompdf->setHttpContext($ctx)	(tidak ada yang setara)	NextPDF tidak mengambil sumber daya jarak jauh melalui stream context; lihat Tidak didukung / tidak ada padanan langsung.

Contoh kode — Mulai cepat

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

Contoh kode — Produksi

Bagian ini mencerminkan examples/08-html-basic.php, contoh pendukung yang dapat dijalankan untuk panduan ini, dengan ukuran kertas dan margin non-standar yang dinyatakan eksplisit. Ini setara dengan pemanggilan setPaper() Dompdf ditambah konfigurasi margin 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);">

Kasus tepi & jebakan

• Tidak ada render dua fase. Kode Dompdf yang memeriksa keadaan di antara render() dan output(), seperti membaca jumlah halaman, tidak memiliki analog NextPDF tepat di batas tersebut. Sebagai gantinya, kueri dokumen setelah writeHtml().
• Pengodean. NextPDF menghilangkan parameter $encoding milik Dompdf. Konversikan input ke UTF-8 sebelum writeHtml(). Meneruskan byte Latin-1 menghasilkan mojibake, bukan kesalahan.
• render() dibiarkan terpasang. Pemanggilan bergaya $dompdf->render() yang tersisa tidak memiliki metode NextPDF dan gagal dengan kesalahan fatal “undefined method”. Hapus saat peralihan; jangan buat stub.
• PHP sebaris. enable_php milik Dompdf mengevaluasi <script type="text/php">. NextPDF dengan sengaja tidak memiliki eksekusi PHP di dalam dokumen karena itu adalah permukaan serangan injeksi. Pindahkan logika itu ke kode PHP Anda sebelum writeHtml().
• Resolusi sumber daya relatif. Dompdf meresolusi <img src> terhadap triplet path/protocol/host dasar. NextPDF meresolusi terhadap working set dokumen. Selama migrasi, teruskan path absolut atau data URI yang telah diresolusi sebelumnya untuk menghilangkan variabel tersebut.

Kinerja

writeHtml() melakukan tata letak dalam satu lintasan streaming tunggal, sebagaimana dijelaskan dalam catatan keputusan arsitektur ADR-001. Tidak ada objek pohon frame perantara yang dipertahankan setelah tata letak, sehingga puncak memori mengikuti ukuran dokumen, bukan jumlah node DOM. Anggaran kinerja untuk contoh panduan ini adalah wall_ms: 2000, peak_mb: 128. Untuk dokumen besar, pecah HTML pada batas addPage() alih-alih membangun satu string berukuran beberapa megabyte.

Catatan keamanan

• Tidak ada pengambilan jarak jauh melalui stream context. NextPDF tidak mengimplementasikan jalur pengambilan jarak jauh setHttpContext() / enable_remote milik Dompdf. Lakukan resolusi dan validasi aset jarak jauh di aplikasi Anda, lalu teruskan byte atau data URI. Ini menghilangkan permukaan server-side request forgery (SSRF) yang dibawa oleh enable_remote.
• Tidak ada eksekusi kode di dalam dokumen. Ketiadaan padanan enable_php adalah pengerasan yang disengaja, bukan celah.
• Metadata dokumen yang Anda atur melalui setter bertipe ditulis ke kamus informasi ISO 32000-2 §14 / Extensible Metadata Platform (XMP) (iso32000_2_sec14#x1.x5.p5). Jangan menempatkan rahasia di sana.

Konformansi

Pernyataan	Spesifikasi	Klausul	reference_id
Konten halaman adalah representasi aliran konten dalam model opaque/transparent.	ISO 32000-2	§8
Ukuran kertas dipetakan ke kotak batas objek halaman.	ISO 32000-2	§7
Fon HTML ditulis sebagai program fon embedded/subset.	ISO 32000-2	§9
Pemrosesan ruang kosong/pemenggalan baris bersifat spesifik per mesin.	CSS Text 3	§6.5

NextPDF menghasilkan konten ISO 32000-2. Ini tidak mengklaim bahwa dokumen Dompdf yang dimigrasikan identik secara visual. Tinjau ulang output setiap kali Anda mengganti renderer.

Konteks komersial

Tidak berlaku. Core mencakup jalur migrasi HTML-ke-PDF ini.

Lihat juga

• Indeks migrasi
• Migrasi dari mPDF
• Matriks dukungan CSS
• Modul Html

---

Detail migrasi (bagian wajib R6)

Untuk siapa ini

Gunakan bagian ini jika tim Anda menjalankan dompdf/dompdf untuk HTML-ke-PDF sisi server dan ingin beralih ke mesin NextPDF. Jika Anda hanya memanggil loadHtml / setPaper / render / output, pemetaan verba mencakup seluruh permukaan API Anda.

Cakupan

Dalam cakupan: verba fasad Dompdf, kunci Options, ekspektasi paritas fitur CSS, resolusi sumber daya, dan metadata. Di luar cakupan: objek internal FrameTree/Canvas/Stylesheet milik Dompdf. NextPDF tidak memiliki analog publik, jadi jangan memigrasikan kode yang mengakses objek-objek itu; gantikan dengan API publik.

Peta kompatibilitas

Di sini, cakupan berarti kompatibilitas perilaku, bukan shim siap pakai. NextPDF tidak memiliki shim kelas Dompdf (tidak seperti jalur TCPDF; lihat /migration/tcpdf-compat/). Tulis ulang setiap lokasi pemanggilan menggunakan pemetaan verba. Baris Terverifikasi pada Matriks dukungan CSS menjadi acuan penuh untuk ekspektasi fitur CSS. Panduan ini tidak menyatakan ulang status per-properti.

Peta opsi dan konfigurasi

Opsi Dompdf (kunci / setter)	NextPDF	Catatan
default_paper_size / setDefaultPaperSize() ; setPaper($size,...)	Config->pageSize (VO PageSize)	Ukuran bernama menjadi dimensi titik yang eksplisit. new PageSize(595.276, 841.890, 'A4') adalah standar createStandalone().
default_paper_orientation / setDefaultPaperOrientation()	tukar PageSize width/height	NextPDF tidak memiliki flag orientasi. Halaman lanskap adalah PageSize dengan width > height.
dpi / setDpi()	(bukan pengaturan global)	NextPDF bekerja dalam titik PDF (1/72 in). Penentuan ukuran gambar bersifat per-gambar, bukan pengali dots per inch (DPI) dokumen. Hitung ulang ukuran piksel tetap ke titik.
enable_remote / setIsRemoteEnabled()	(tidak ada yang setara — secara sengaja)	Lakukan resolusi aset jarak jauh di kode Anda; lihat Catatan keamanan.
enable_html5_parser / setIsHtml5ParserEnabled()	(selalu mengurai HTML)	Tidak ada tombol; parser adalah pipeline-nya.
enable_php / setIsPhpEnabled()	(tidak ada yang setara — secara sengaja)	PHP di dalam dokumen tidak didukung. Pindahkan logika keluar dari templat.
font_dir / setFontDir()	Config->fontsDirectory	String untuk satu direktori fon.
chroot	(resolusi di aplikasi)	NextPDF tidak menerima opsi jail sistem berkas. Validasi path sebelum meneruskan byte.
default_font / setDefaultFont()	CSS font-family / fon terdaftar	Atur standar di lembar gaya dasar atau registrasi fon Anda, bukan opsi global.
enable_font_subsetting / setIsFontSubsettingEnabled()	(selalu melakukan subset)	NextPDF selalu melakukan subset fon yang disematkan (ISO 32000-2 §9, iso32000_2_sec9#x1.x45.p7). Tidak ada mode “mati”; jalur Dompdf dengan flag nonaktif tidak memiliki padanan dan tidak diperlukan.

Perbedaan perilaku

• Mesin tata letak. Dompdf dan NextPDF menggunakan implementasi tata letak CSS yang independen. Penciutan ruang kosong dan pemenggalan baris telah dispesifikasikan, tetapi tetap sensitif terhadap mesin (CSS Text 3 §6.5, css_text_3#x1.x6.x5.p20). Harapkan perbedaan pelipatan baris dan paginasi pada teks yang padat. Buat ulang baseline diff visual setelah migrasi.
• Batas render. Tidak ada batas dua fase render()/output() (lihat Kasus tepi).
• Resolusi sumber daya. Penanganan base-path/protocol/host berbeda dari working set dokumen.
• Model DPI. Titik PDF berbeda dari pengali DPI milik Dompdf.
• Metadata. Pasangan addInfo() format bebas berbeda dari setter bertipe (ISO 32000-2 §14, iso32000_2_sec14#x1.x5.p5).

Ini adalah perbedaan perilaku yang terdokumentasi, bukan cacat pada salah satu mesin.

Tidak didukung / tidak ada padanan langsung

• enable_php (PHP di dalam dokumen) — sengaja tidak ada.
• setHttpContext() / pengambilan jarak jauh enable_remote — sengaja tidak ada.
• Akses publik ke FrameTree / Canvas / Stylesheet — tidak ada analog publik.
• dpi sebagai pengali global dokumen — tidak dimodelkan.

Kode yang bergantung pada hal-hal ini tidak “bermigrasi” begitu saja. Hapus atau ekspresikan ulang dalam kode aplikasi menggunakan baris-baris di atas.

Urutan migrasi yang aman

1. Tambahkan nextpdf/core bersama dompdf/dompdf. Jangan hapus Dompdf dulu.
2. Pilih satu dokumen berisiko rendah. Tulis ulang lokasi pemanggilannya dengan pemetaan verba, dan hapus pemanggilan render().
3. Hasilkan kedua PDF dari input yang sama dan bandingkan secara visual. Perlakukan perbedaan sebagai hal yang diharapkan karena mesinnya independen, dan putuskan penerimaan per dokumen.
4. Konversikan penggunaan opsi dengan peta opsi; hitung ulang ukuran turunan DPI menjadi titik.
5. Selesaikan resolusi aset jarak jauh dan relatif terlebih dahulu menjadi path absolut atau data URI untuk menghilangkan variabel resolusi.
6. Ulangi per dokumen, dari yang paling rendah risikonya ke yang tertinggi. Pertahankan kedua mesin tetap terpasang hingga lokasi pemanggilan terakhir dialihkan.
7. Hapus dompdf/dompdf dari composer.json hanya setelah peralihan terakhir.

Menguji migrasi

• Buat snapshot output Dompdf dari dokumen-dokumen yang representatif sebelum mengubah kode. Gunakan input emas, bukan byte emas, karena byte-nya akan berbeda.
• Untuk setiap dokumen yang dimigrasikan, jalankan output NextPDF melalui pemeriksaan penerimaan Anda sendiri, seperti diff visual atau asersi ekstraksi teks. Perilaku pipeline HTML NextPDF sendiri tercakup oleh examples/08-html-basic.php dan suite Html core tests/. Penerimaan migrasi bersifat spesifik per dokumen, dan Anda bertanggung jawab untuk membuat asersinya.
• Tambahkan uji regresi untuk setiap dokumen yang dimigrasikan agar pembaruan mesin di masa depan dapat tertangkap.

Bukti / keterlacakan

Setiap pernyataan tentang perilaku NextPDF di halaman ini didukung oleh uji, contoh, tanda tangan sumber di dalam repo, atau catatan keputusan arsitektur (ADR). Untuk properti format PDF, dukungannya berasal dari klausul ISO 32000-2 / CSS yang di-pin melalui Retrieval-Augmented Generation (RAG) di frontmatter citations: dan tabel Konformansi. Perilaku Dompdf hanya diasersikan sebagai “mesin independen — harapkan perbedaan yang terdokumentasi”. Halaman ini tidak mengklaim paritas apa pun kecuali ada artefak di dalam repo yang membuktikannya.

Klaim perilaku NextPDF	Bukti di dalam repo (path)
Halaman default createStandalone() adalah A4 potret (595.276 × 841.890 pt).	src/Core/Config.php (default PageSize(595.276, 841.890, 'A4')); tests/Unit/Core/DocumentCreateStandaloneAndConfigWithersEdgeCaseTest.php (createStandaloneWithNullConfigBuildsDocumentWithA4Defaults).
writeHtml() menata dalam satu lintasan streaming tunggal; tidak ada DOM yang dipertahankan setelah tata letak.	docs/architecture/adr/ADR-001-stream-based-rendering-pipeline.md; src/Core/Concerns/HasTextOutput.php (writeHtml()).
writeHtml() otomatis membuat halaman pertama ketika tidak ada halaman.	tests/Unit/Core/Concerns/DocumentTextOutputFontSubsettingAndBorderEdgeCaseTest.php (writeHtmlAutoCreatesFirstPageWhenNoPagesExist).
output() / save() / getPdfData() adalah verba emisi (tidak ada dua fase render/output).	src/Core/Concerns/HasOutput.php (output(), save(), getPdfData()); tests/Unit/Core/Concerns/DocumentOutputDestinationDispatchTest.php.
Tujuan output adalah enum NextPDF\Contracts\OutputDestination (Inline/Download/File/String).	src/Contracts/OutputDestination.php; tests/Unit/Core/Concerns/DocumentOutputDestinationDispatchTest.php.
Fon HTML selalu ditulis sebagai program embedded/subset.	tests/Unit/Core/Concerns/DocumentTextOutputFontSubsettingAndBorderEdgeCaseTest.php (recordUsedCharactersAffectsFontSubsetting); ISO 32000-2 §9 (citations: frontmatter).
Setter metadata bertipe (setTitle/setAuthor) menggantikan addInfo() format bebas.	src/Core/Concerns/HasMetadata.php (setTitle(), setAuthor()); tests/Unit/Core/Concerns/DocumentInfoMetadataSetterBaselineTest.php.
Pipeline HTML ujung-ke-ujung (pendukung yang dapat dijalankan untuk panduan ini).	examples/08-html-basic.php; suite Html core tests/Unit/Html/.
Ruang kosong/pemenggalan baris bersifat spesifik per mesin (delta tata letak).	CSS Text 3 §6.5 (citations: frontmatter + Konformansi).

Rollback

Karena kedua paket tetap terpasang hingga peralihan terakhir, rollback untuk lokasi pemanggilan yang belum dikonversi berarti mengembalikan lokasi pemanggilan itu ke jalur Dompdf. Setelah peralihan terakhir, rollback berarti memulihkan dompdf/dompdf dan lokasi pemanggilan sebelumnya dari kendali versi. Tidak ada migrasi data yang terlibat; hanya perubahan kode.

Pertimbangan kinerja

Lihat Kinerja. Model lintasan tunggal berarti migrasi tidak memperkenalkan biaya retensi pohon frame. Perubahan utama pada biaya per-dokumen adalah resolusi aset lebih awal dari langkah 5, yang dapat Anda cache.

Jebakan umum

• Membiarkan render() tetap ada, yang menyebabkan fatal undefined method.
• Meneruskan byte non-UTF-8 setelah menghapus $encoding, yang menyebabkan mojibake diam-diam.
• Mengharapkan output yang identik byte demi byte atau piksel demi piksel dari mesin yang independen. Panduan ini tidak pernah mengklaim shim siap pakai atau kompatibilitas 100%.
• Bergantung pada templat enable_php, yang harus difaktorkan ulang keluar.
• Memperlakukan matriks dukungan CSS sebagai sekadar saran. Itu adalah otoritas fitur Terverifikasi untuk apa yang harus diharapkan.