Migrasi dari mPDF ke NextPDF

Sekilas

Panduan ini membantu Anda memindahkan basis kode berbasis mPDF ke inti NextPDF. Di mPDF, panggilan konten utama adalah WriteHTML(), yang dipetakan langsung ke Document::writeHtml(). Sebagian besar pekerjaan terletak pada pemetaan larik konfigurasi konstruktor (mPDF mengonfigurasi semuanya melalui satu larik asosiatif yang diteruskan ke new Mpdf([...])) dan delta penanganan fon. NextPDF dan mPDF adalah mesin yang independen, sehingga dokumen yang dimigrasikan kompatibel dengan keluaran mPDF, bukan identik byte demi byte dengannya. Panduan ini mencakup pemetaan verba, pemetaan larik konfigurasi, delta fon, delta dukungan Cascading Style Sheets (CSS), perbedaan perilaku, dan urutan yang aman.

Matriks dukungan Cascading Style Sheets (CSS) mendefinisikan fitur Hypertext Markup Language (HTML) dan CSS mana yang sudah Terverifikasi. Panduan ini menjelaskan perilaku; tidak menyatakan kesetaraan visual dengan mPDF.

Pemasangan

composer require nextpdf/core:^3

Pertahankan mpdf/mpdf tetap terpasang selama Anda bermigrasi. Hapus setelah peralihan akhir (lihat urutan migrasi yang aman).

Ikhtisar konseptual

Objek Mpdf milik mPDF menggabungkan konfigurasi dan rendering di balik satu antarmuka. Larik konstruktor mengonfigurasinya, lalu WriteHTML() beserta verba paginasi (AddPage, SetHTMLHeader, SetHTMLFooter) menjalankannya. NextPDF memisahkan konfigurasi ke dalam objek nilai NextPDF\Core\Config yang imutabel dan menulis konten dengan Document::writeHtml(). Tidak ada string “mode” pada konstruktor. NextPDF mengurai HTML yang Anda teruskan, lalu menghasilkan dokumen dengan save(), output(), atau getPdfData().

Fon: mPDF disertai direktori fon, peta fontdata, dan kumpulan fallback “core fonts”. NextPDF menyelesaikan fon dari satu direktori fon ditambah pencocokan CSS font-family, dan selalu melakukan subset pada fon yang disematkan (International Organization for Standardization (ISO) 32000-2 §9, iso32000_2_sec9#x1.x45.p7). Pencocokan fon dan fallback bersifat spesifik per mesin (CSS Fonts 4 §5.5, css_fonts_4#x1.x5.x5.x1.p13), sehingga substitusi glif dapat berbeda. Ini adalah delta kasatmata yang utama, dibahas dalam delta penanganan fon.

Permukaan API

API HTML NextPDF didokumentasikan dalam referensi modul Html. Titik masuk inti adalah Document::createStandalone(), Document::writeHtml(string $html): static, Document::writeHtmlCell(...), Document::addPage(), Document::output(?string, OutputDestination), Document::save(string $path): void, Document::getPdfData(): string, dan objek nilai NextPDF\Core\Config.

Pemetaan verba API

Nama metode publik mPDF di bawah ini telah dikonfirmasi berdasarkan repositori publik hulu (mpdf/mpdf, development); lihat sidecar provenans _source-sidecar-upstream-api.md di dalam repo. Tidak ada teks dokumentasi hulu yang direproduksi.

mPDF	NextPDF	Catatan
`new Mpdf([...])`	`Document::createStandalone($config)`	Larik konfigurasi mPDF dipetakan ke `NextPDF\Core\Config`; lihat pemetaan konfigurasi. Gunakan `DocumentFactory` untuk worker yang berumur panjang.
`$mpdf->WriteHTML($html)`	`$doc->writeHtml($html)`	Pemetaan langsung. Argumen kedua mPDF `$mode` (dokumen lengkap vs. hanya CSS vs. elemen) tidak memiliki padanan di NextPDF; teruskan HTML lengkap.
`$mpdf->WriteFixedPosHTML(...)`	`$doc->writeHtmlCell(...)`	Wilayah HTML yang diposisikan dan diberi ukuran; petakan argumen x/y/width/height.
`$mpdf->AddPage(...)`	`$doc->addPage()`	NextPDF tidak menerima penggantian orientation/format/margin mPDF sebagai argumen per panggilan; ubah model dokumen di antara panggilan saja.
`$mpdf->SetHTMLHeader($html)` / `SetHTMLFooter($html)`	header/footer melalui Layout API	Header HTML berjalan dari mPDF dipetakan ke mekanisme header/footer NextPDF, bukan ke HTML sebaris di bagian atas badan dokumen.
`$mpdf->Output($name, $dest)`	`$doc->output($name, OutputDestination::…)`	Karakter tujuan mPDF (`I`/`D`/`F`/`S`) dipetakan ke enum `OutputDestination` (`Inline`/`Download`/file melalui `save()`/string melalui `getPdfData()`).
`$mpdf->Output('','S')`	`$doc->getPdfData()`	Mengembalikan byte.
`$mpdf->Output($path,'F')`	`$doc->save($path)`	Menulis ke jalur berkas.
`$mpdf->SetTitle($t)`	`$doc->setTitle($t)`	Ditulis ke kamus informasi / Extensible Metadata Platform (XMP) ISO 32000-2 §14 (`iso32000_2_sec14#x1.x5.p5`).
`$mpdf->SetProtection($perms,...)`	`$doc->setEncryption(...)` (Security API)	Izin bergantung pada pembaca yang kooperatif, bukan kontrol akses — lihat catatan keamanan.

Contoh kode — Mulai cepat

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

Contoh kode — Produksi

Contoh ini selaras dengan examples/04-text-and-fonts.php, contoh pendukung yang dapat dijalankan untuk konsep penanganan fon dalam panduan ini. Contoh ini menggunakan ukuran halaman eksplisit, margin, dan badan konten yang mencontohkan pemilihan fon.

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

Kasus pinggir & gotcha

Argumen $mode pada WriteHTML. WriteHTML($html, $mode) milik mPDF (2 = hanya CSS, 1 = elemen) tidak memiliki padanan. Letakkan CSS di dalam HTML yang Anda teruskan; tidak ada urutan “tulis CSS lalu tulis badan”.
Penggantian per-AddPage. mPDF memungkinkan AddPage() mengubah format/orientation di tengah dokumen melalui argumen. NextPDF addPage() tidak menerima argumen semacam itu; perubahan ukuran model dilakukan melalui dokumen, bukan melalui panggilan halaman.
HTML header/footer. mPDF mendaftarkan header berjalan sebagai fragmen HTML terpisah; jangan menempelkannya ke dalam badan dokumen. Petakan ke mekanisme header/footer NextPDF.
Nama fon. mPDF menormalkan nama fon melalui tabel fontdata/core-font-nya. NextPDF mencocokkan CSS font-family terhadap direktori fon; alias mPDF yang sebelumnya teratasi secara senyap mungkin memerlukan @font-face/family.
Karakter tujuan. 'I'/'D'/'F'/'S' tidak diterima; gunakan enum OutputDestination atau save()/getPdfData().

Kinerja

writeHtml() berjalan dalam satu lintasan (ADR-001); puncak memori mengikuti ukuran dokumen, bukan Document Object Model (DOM) yang dipertahankan. Anggaran untuk contoh dalam panduan ini: wall_ms: 2000, peak_mb: 128. Untuk dokumen yang panjang, pisahkan konten ke beberapa panggilan addPage() alih-alih meneruskan satu string raksasa. Ini adalah panduan yang sama seperti pada pemecahan $mode mPDF, tetapi dinyatakan melalui model halaman.

Catatan keamanan

Perizinan bergantung pada pembaca yang kooperatif. SetProtection() → setEncryption() menyediakan kerahasiaan, bukan kontrol akses: bit izin ISO bergantung pada pembaca yang kooperatif. Jangan menyajikan enkripsi sebagai kontrol akses kepada pengguna.
Metadata. SetTitle() dan informasi dokumen ditulis ke kamus informasi / XMP ISO 32000-2 §14 (iso32000_2_sec14#x1.x5.p5); jangan pernah menyimpan rahasia di sana.
NextPDF tidak mengeksekusi skrip di dalam dokumen; tidak ada arahan mPDF yang mengubahnya di sini.

Konformansi

Pernyataan	Spesifikasi	Klausa
Fon ditulis sebagai program fon embedded/subset.	ISO 32000-2	§9
Format halaman/margin dipetakan ke kotak batas halaman.	ISO 32000-2	§7
Metadata judul / proteksi ditulis ke kamus informasi / XMP.	ISO 32000-2	§14
Pencocokan fon / fallback bersifat spesifik per mesin.	CSS Fonts 4	§5.5

NextPDF menghasilkan konten ISO 32000-2; ia tidak menyatakan identitas visual dengan mPDF. Tinjau ulang keluaran setiap kali Anda mengganti renderer.

Konteks komersial

Tidak berlaku. Inti NextPDF mencakup jalur migrasi mPDF yang dijelaskan di sini.

Lihat juga

Detail migrasi (bagian wajib R6)

Untuk siapa ini

Tim yang menjalankan mpdf/mpdf untuk HTML-ke-PDF sisi server. Jika kode Anda dibangun di sekitar new Mpdf([...]) + WriteHTML + Output (+ header/footer opsional), maka pemetaan verba dan pemetaan konfigurasi mencakupnya.

Ruang lingkup

Dalam lingkup: larik konfigurasi konstruktor Mpdf, WriteHTML/Output/AddPage, headers/footers, fon, proteksi, metadata. Di luar lingkup: kelas internal mPDF dan permukaan helper Quick Response (QR)/barcode/watermark. Petakan semua itu ke modul NextPDF yang sesuai — Barcode, Graphics — yang tidak dibahas di sini.

Pemetaan kompatibilitas

Kompatibilitas perilaku, bukan shim siap-pakai: NextPDF tidak menyediakan shim kelas Mpdf. Tulis ulang setiap lokasi panggilan. Gunakan baris Terverifikasi pada matriks dukungan CSS untuk menetapkan ekspektasi fitur CSS.

Pemetaan larik konfigurasi konstruktor

Kunci konfigurasi mPDF di bawah ini telah dikonfirmasi berdasarkan repositori publik hulu (mpdf/mpdf, development). Tidak ada teks dokumentasi hulu yang direproduksi.

Kunci konfigurasi mPDF	NextPDF	Catatan
`mode`	(tidak ada padanan)	String mode mPDF (`'utf-8'`, `'c'`, `'+aCJK'`, …) memilih perilaku font/script. NextPDF selalu Unicode; teks Tionghoa, Jepang, dan Korea (CJK) ditangani melalui pemilihan fon, bukan mode. Hapus kunci tersebut.
`format`	`Config->pageSize` (objek nilai `PageSize` (VO))	Format bernama menjadi dimensi titik eksplisit; larik `[w,h]` dipetakan ke `PageSize`.
`orientation`	tukar `PageSize` width/height	Tidak ada flag orientasi; lanskap berarti width > height.
`default_font_size`	font-size dasar CSS	Atur ini di lembar gaya dasar Anda, bukan di kunci konstruktor.
`default_font`	CSS `font-family` / fon terdaftar	Atur keluarga fon default melalui CSS / registrasi fon.
`margin_left` / `margin_right` / `margin_top` / `margin_bottom`	`Config->margins` (`Margin` VO) dalam titik	Gunakan satu objek nilai `Margin`; urutan konstruktornya adalah `Margin(top, right, bottom, left)` (verifikasi terhadap `src/ValueObjects/Margin.php`), bukan urutan kunci mPDF.
`margin_header` / `margin_footer`	offset header/footer melalui Layout API	Petakan ini ke konfigurasi header/footer NextPDF, bukan ke kunci konstruktor.

Delta penanganan fon

Direktori fon tunggal. Daftar direktori fon mPDF, peta fontdata, dan fallback core-font menyatu menjadi Config->fontsDirectory ditambah pencocokan CSS font-family.
Selalu di-subset. NextPDF selalu melakukan subset pada fon yang disematkan (ISO 32000-2 §9, iso32000_2_sec9#x1.x45.p7); flag subset mPDF tidak memiliki padanan dan tidak diperlukan.
Pencocokan bersifat spesifik per mesin. Pencocokan fon dan fallback berbeda menurut mesin (CSS Fonts 4 §5.5, css_fonts_4#x1.x5.x5.x1.p13); alias fon mPDF mungkin memerlukan @font-face eksplisit atau nama keluarga yang persis. Tetapkan ulang baseline rendering glif setelah migrasi. Perbedaan substitusi adalah hal yang diharapkan, bukan cacat.

Perbedaan perilaku

Substitusi fon (lihat di atas) — delta kasatmata yang utama.
Tidak ada $mode pada WriteHTML — teruskan HTML lengkap dengan CSS sebaris.
Tidak ada penggantian format per-AddPage — perubahan ukuran model dilakukan melalui dokumen.
Perizinan bergantung pada pembaca yang kooperatif (lihat catatan keamanan).
Mesin tata letak independen — pembungkusan baris / paginasi berbeda pada konten yang padat; tetapkan ulang baseline diff visual.

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

Tidak didukung / tanpa padanan langsung

mode string konstruktor — tidak dimodelkan (selalu Unicode).
Argumen format/orientation/margin per-AddPage() — bukan argumen di NextPDF.
Peta fontdata mPDF — digantikan oleh direktori fon + pencocokan CSS.
Karakter tujuan 'I'/'D'/'F'/'S' mPDF — digantikan oleh enum OutputDestination + save()/getPdfData().

Urutan migrasi yang aman

Tambahkan nextpdf/core berdampingan dengan mpdf/mpdf; pertahankan mPDF tetap terpasang untuk saat ini.
Pilih satu dokumen berisiko rendah. Konversikan new Mpdf([...]) melalui pemetaan konfigurasi dan WriteHTML/Output melalui pemetaan verba.
Daftarkan fon yang digunakan dokumen di Config->fontsDirectory, dan tambahkan deklarasi @font-face/family eksplisit untuk setiap alias mPDF.
Hasilkan kedua PDF untuk masukan yang sama dan bandingkan secara visual. Perbedaan (substitusi fon, pembungkusan baris) wajar terjadi pada mesin yang independen — terima per dokumen.
Petakan setiap HTML header/footer ke mekanisme header/footer NextPDF.
Ulangi per dokumen, mulai dari yang berisiko paling rendah; pertahankan mPDF tetap terpasang hingga peralihan terakhir.
Hapus mpdf/mpdf dari composer.json setelah peralihan akhir.

Menguji migrasi

Ambil snapshot keluaran mPDF untuk dokumen representatif sebelum Anda mengubah kode (masukan golden; byte-nya akan berbeda).
Untuk setiap dokumen yang dimigrasikan, pastikan penerimaan melalui pemeriksaan Anda sendiri (diff visual
- ekstraksi teks). Perilaku fon/HTML NextPDF dicakup oleh examples/04-text-and-fonts.php dan examples/08-html-basic.php ditambah suite tests/ Html/Font inti. Penerimaan migrasi bersifat spesifik per dokumen dan tetap menjadi tanggung jawab Anda.
Tambahkan satu uji regresi per dokumen yang dimigrasikan.

Bukti / keterlacakan

Setiap pernyataan perilaku NextPDF pada halaman ini didukung oleh uji, contoh, tanda tangan sumber, atau architecture decision record (ADR) di dalam repo, atau, untuk properti format-PDF, oleh klausa ISO 32000-2 / CSS yang dirujuk melalui RAG (retrieval-augmented generation) dalam citations: di front-matter dan tabel Konformansi. Perilaku mPDF hanya dinyatakan sebagai “mesin independen — harapkan perbedaan yang terdokumentasi”; halaman ini tidak mengeklaim paritas apa pun yang tidak dibuktikan oleh artefak di dalam repo.

Klaim perilaku NextPDF	Bukti di dalam repo (jalur)
`WriteHTML()` dipetakan langsung ke `Document::writeHtml(string $html): static`.	`src/Core/Concerns/HasTextOutput.php` (`writeHtml()`); `examples/08-html-basic.php`.
`WriteFixedPosHTML(...)` dipetakan ke `writeHtmlCell(...)`.	`src/Core/Concerns/HasTextOutput.php` (`writeHtmlCell()`).
`createStandalone()` halaman default adalah A4 potret (`595.276 × 841.890 pt`).	`src/Core/Config.php` (default `PageSize`); `tests/Unit/Core/DocumentCreateStandaloneAndConfigWithersEdgeCaseTest.php`.
`Margin` urutan konstruktor adalah `(top, right, bottom, left)`.	`src/ValueObjects/Margin.php` (urutan properti yang dipromosikan).
Tujuan keluaran adalah enum `NextPDF\Contracts\OutputDestination`; `'I'/'D'/'F'/'S'` tidak diterima.	`src/Contracts/OutputDestination.php` (kasus `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()` dipetakan ke `setEncryption(...)`; izin bergantung pada pembaca yang kooperatif.	`src/Core/Concerns/HasSecurity.php` (`setEncryption()`); ISO 32000-2 §14 (front-matter `citations:`).
`SetTitle()` → `setTitle()`; metadata ditulis ke kamus informasi / XMP.	`src/Core/Concerns/HasMetadata.php` (`setTitle()`); `tests/Unit/Core/Concerns/DocumentInfoMetadataSetterBaselineTest.php`; ISO 32000-2 §14 (front-matter `citations:`).
Fon selalu disematkan sebagai program subset.	`tests/Unit/Core/Concerns/DocumentTextOutputFontSubsettingAndBorderEdgeCaseTest.php`; `examples/04-text-and-fonts.php`; ISO 32000-2 §9 (front-matter `citations:`).
Pencocokan fon / fallback bersifat spesifik per mesin (delta substitusi).	CSS Fonts 4 §5.5 (front-matter `citations:` + Konformansi).
`writeHtml()` berjalan dalam satu lintasan; puncak memori mengikuti ukuran dokumen.	`docs/architecture/adr/ADR-001-stream-based-rendering-pipeline.md`.

Rollback

Kedua paket tetap terpasang hingga peralihan akhir, sehingga rollback per lokasi panggilan berarti mengembalikan lokasi panggilan tersebut ke jalur mPDF. Setelah peralihan akhir, rollback berarti memulihkan mpdf/mpdf dan kode sebelumnya dari kontrol versi. Tidak ada migrasi data yang terlibat.

Pertimbangan kinerja

Lihat Kinerja. Model satu lintasan menghilangkan biaya buffer yang dipertahankan mPDF. Biaya baru per dokumen adalah penyelesaian fon secara eager (langkah 3), yang dapat di-cache melalui direktori fon.

Jebakan umum

Mempertahankan kunci mode dan mengharapkan perilaku CJK darinya; NextPDF menghapusnya, dan CJK adalah pemilihan fon.
Meneruskan WriteHTML($html, 2) (mode hanya CSS); gunakan CSS sebaris sebagai gantinya.
Menempelkan HTML header/footer ke dalam badan.
Mengharapkan alias mPDF teratasi ke fon yang sama tanpa keluarga yang eksplisit.
Mengharapkan keluaran byte/pixel-identical (mesin independen — panduan ini tidak pernah mengeklaim siap-pakai atau kompatibilitas 100%).
Memperlakukan matriks dukungan CSS sebagai sekadar anjuran; matriks itu adalah otoritas fitur Terverifikasi.