Lewati ke konten
getnextpdf.com

Migrasi dari FPDF ke NextPDF

Panduan ini membantu Anda memindahkan basis kode berbasis FPDF ke NextPDF core. FPDF adalah salah satu pustaka Portable Document Format (PDF) PHP legacy yang paling banyak diterapkan, dan permukaan penggambarannya — AddPage, SetFont, Cell, MultiCell, Write, Text, Image, Output yang digerakkan oleh kursor x/y manual — memetakan dengan rapi ke API cell/text milik NextPDF sendiri, karena metode penggambaran tingkat-rendah NextPDF mengikuti garis keturunan FPDF/TCPDF yang sama. NextPDF bukan klon FPDF yang drop-in, meski begitu: ia adalah engine PDF 2.0 modern dengan tipe ketat, subsetting fon, penandatanganan, PDF/A, dan aksesibilitas (tagged PDF). Dua pergeseran nyata adalah model unit (NextPDF bekerja dalam PDF point; FPDF default ke milimeter) dan verb keluaran (sebuah enum OutputDestination bertipe alih-alih karakter 'I'/'D'/'F'/'S' FPDF).

Tidak ada shim kelas FPDF di core. Tulis ulang setiap call site menggunakan pemetaan verb. Jika Anda menginginkan perubahan awal terkecil untuk basis kode TCPDF 6.x sebagai gantinya, lihat adapter kompatibilitas TCPDF, yang mengirimkan jalur drop-in yang hampir kompatibel-sumber; FPDF tidak punya adapter semacam itu.

Terminal window
composer require nextpdf/core:^3

Pertahankan setasign/fpdf (atau fpdf/fpdf Anda) terpasang selama Anda migrasi. Hapus setelah cutover final (lihat urutan migrasi yang aman).

FPDF dan NextPDF berbagi model mental yang sama: sebuah dokumen yang terdiri dari halaman, sebuah kursor (posisi x/y saat ini), dan verb yang menggambar pada atau memajukan kursor itu. SetXY, Cell, Ln, dan MultiCell semuanya membaca dan memutasi kursor di kedua pustaka, sehingga sebagian besar kode FPDF prosedural diterjemahkan baris demi baris.

Perbedaannya disengaja, bukan kebetulan:

  • Unit. Constructor FPDF (new FPDF($orientation, $unit, $size)) default ke milimeter. NextPDF bekerja dalam PDF point (1 pt = 1/72 in, ISO 32000-2 §7). Tidak ada tuas unit selebar-dokumen — konversi mm ke point sekali (pt = mm * 72 / 25.4).
  • Arah Y tetap sama bagi Anda. Seperti FPDF, koordinat pengguna NextPDF menempatkan y = 0 di puncak halaman dan bertambah ke bawah, sehingga aritmetika kursor diport langsung. NextPDF mengonversi ke origin kiri-bawah PDF-native secara internal.
  • Konstruksi bersifat eksplisit. FPDF melipat orientasi, unit, dan ukuran ke dalam constructor; NextPDF menerima sebuah value object NextPDF\Core\Config yang immutable (ukuran halaman, margin, direktori fon) dan sebuah addPage() eksplisit.
  • Selalu Unicode, selalu subset. Build core FPDF adalah Latin-1 dan membutuhkan varian tFPDF/UTF-8 untuk Unicode. NextPDF UTF-8 di seluruhnya dan selalu menanamkan fon sebagai program subset (ISO 32000-2 §9). File AddFont/metrik-fon FPDF tidak punya analog; daftarkan sebuah direktori fon TrueType/OpenType dan pilih keluarganya berdasarkan nama.

Titik masuk core yang digunakan di bawah adalah Document::createStandalone(), Document::addPage(), Document::setFont(), Document::cell(), Document::multiCell(), Document::text(), Document::write(), Document::ln(), Document::image(), accessor kursor (setXY/setX/ setY/getX/getY), Document::output(?string, OutputDestination), Document::save(string $path): void, Document::getPdfData(): string, dan value object NextPDF\Core\Config. Referensi lengkap untuk metode core penggambaran, teks, dan keluaran ini berada di modul core dan indeks referensi, yang dihasilkan otomatis dari PHPDoc. Modul Html adalah bacaan terkait untuk HTML-ke-PDF, bukan referensi untuk verb di halaman ini.

Nama metode publik FPDF sudah lama dan dikenal luas. Kolom NextPDF di bawah dikonfirmasi terhadap tanda tangan kode sumber core (lihat Bukti / keterlacakan).

FPDFNextPDFCatatan
new FPDF($orient, $unit, $size)Document::createStandalone($config)Argumen constructor orientasi/unit/ukuran menjadi sebuah NextPDF\Core\Config (pageSize, margins, fontsDirectory). Tanpa $unit — bekerja dalam point. Halaman default createStandalone() adalah A4 portrait.
$pdf->AddPage($orient, $size)$doc->addPage($size, $orientation)Pemetaan langsung. $size adalah value object PageSize; $orientation adalah enum Orientation (Portrait/Landscape).
$pdf->SetFont($family, $style, $size)$doc->setFont($family, $style, $size)Pemetaan langsung. $style menggunakan kode ''/'B'/'I'/'BI' yang sama (ditambah 'U' garis bawah).
$pdf->Cell($w, $h, $txt, $border, $ln, $align, $fill)$doc->cell($w, $h, $txt, $border, $newLine, $align, $fill)Pemetaan langsung. $align adalah enum Alignment (Left/Center/Right/Justify); $border menerima bool atau sebuah string 'LTRB'; $ln menjadi bool $newLine.
$pdf->MultiCell($w, $h, $txt, $border, $align, $fill)$doc->multiCell($w, $h, $txt, $border, $align)Word-wrap pada metrik fon sebenarnya. Tanpa argumen $fill; gambar sebuah rect() terisi lebih dulu jika Anda butuh latar.
$pdf->Write($h, $txt, $link)$doc->write($h, $txt, $link)Teks mengalir dari kursor; $link melampirkan sebuah anotasi link URL.
$pdf->Text($x, $y, $txt)$doc->text($x, $y, $txt)Teks posisi-absolut. Pemetaan langsung.
$pdf->Ln($h)$doc->ln($h)Pergantian baris ke margin kiri; 0 = tinggi baris default.
$pdf->Image($file, $x, $y, $w, $h)$doc->image($file, $x, $y, $w, $h)Pemetaan langsung; $x/$y/$w/$h nullable (null = kursor saat ini / ukuran intrinsik).
$pdf->SetXY($x, $y) / SetX / SetY$doc->setXY($x, $y) / setX / setYPemetaan langsung. getX()/getY() membaca kursor.
$pdf->SetMargins($l, $t, $r)$doc->setMargins(new Margin($t, $r, $bottom, $l))Satu value object Margin; urutan constructor adalah (top, right, bottom, left)bukan (left, top, right) FPDF. SetMargins FPDF tidak punya argumen bottom (margin bottom-nya berasal dari SetAutoPageBreak($auto, $margin)), jadi pilih $bottom sendiri — umumnya sama dengan margin top, atau berikan margin auto-page-break.
$pdf->SetAutoPageBreak($auto, $margin)$doc->setAutoPageBreak($auto, $margin)Pemetaan langsung.
$pdf->SetDrawColor / SetFillColor / SetTextColor$doc->setDrawColor / setFillColor / setTextColorRGB (r, g, b), atau satu nilai untuk grayscale.
$pdf->Line / Rect / SetLineWidth$doc->line / rect / setLineWidthPemetaan langsung. rect() menerima sebuah string style ('S'/'F'/'DF').
$pdf->SetTitle/SetAuthor/SetSubject/SetKeywords/SetCreator$doc->setTitle/setAuthor/setSubject/setKeywords/setCreatorPemetaan langsung. Mendarat di information dictionary / Extensible Metadata Platform (XMP) ISO 32000-2 §14.
$pdf->Output($dest, $name)$doc->output($name, OutputDestination::…)Karakter destinasi FPDF (I/D/F/S) memetakan ke enum OutputDestination; perhatikan urutan argumen yang bertukar (nama lebih dulu di NextPDF).
$pdf->Output('S')$doc->getPdfData()Mengembalikan byte PDF.
$pdf->Output('F', $path)$doc->save($path)Menulis ke sebuah path file.
$pdf->GetStringWidth($s)(tidak ada metode publik)Lebar string dihitung secara internal selama wrapping cell()/multiCell(); tidak ada verb pengukuran per-string publik. Gerakkan wrapping melalui multiCell() alih-alih mengukur secara manual.
<?php
declare(strict_types=1);
require_once __DIR__ . '/vendor/autoload.php';
use NextPDF\Contracts\Alignment;
use NextPDF\Core\Document;
// FPDF:
// $pdf = new FPDF(); // mm, A4 portrait
// $pdf->AddPage();
// $pdf->SetFont('Arial', 'B', 16);
// $pdf->Cell(40, 10, 'Invoice');
// $pdf->Output('F', 'out.pdf');
// NextPDF — points, default page is A4 portrait:
$doc = Document::createStandalone();
$doc->setTitle('Invoice');
$doc->addPage();
$doc->setFont('Helvetica', 'B', 16.0);
$doc->cell(113.4, 28.3, 'Invoice', false, true, Alignment::Left); // ~40mm x ~10mm in points
$doc->save(__DIR__ . '/out.pdf');
echo "Wrote out.pdf\n";

Contoh ini selaras dengan examples/04-text-and-fonts.php. Ia menggunakan ukuran halaman eksplisit, margin, sebuah direktori fon yang terdaftar, dan model cell-yang-digerakkan-kursor yang sudah digunakan basis kode FPDF.

<?php
declare(strict_types=1);
require_once __DIR__ . '/vendor/autoload.php';
use NextPDF\Contracts\Alignment;
use NextPDF\Contracts\OutputDestination;
use NextPDF\Core\Config;
use NextPDF\Core\Document;
use NextPDF\ValueObjects\Margin;
use NextPDF\ValueObjects\PageSize;
// Equivalent of: new FPDF('P', 'mm', 'A4') + SetMargins(20, 16, 20)
// i.e. FPDF left=20mm, top=16mm, right=20mm. FPDF SetMargins has no bottom
// argument, so we pick bottom = top = 16mm. Convert each mm to points
// (pt = mm * 72 / 25.4): 16mm = 45.354pt, 20mm = 56.693pt.
// Margin constructor order is (top, right, bottom, left) — NOT FPDF's (L, T, R).
$config = new Config(
pageSize: new PageSize(595.276, 841.890, 'A4'),
margins: new Margin(45.354, 56.693, 45.354, 56.693), // top,right,bottom,left in points
fontsDirectory: __DIR__ . '/fonts',
);
$doc = Document::createStandalone($config);
$doc->setTitle('Quarterly Report');
$doc->setAuthor('Finance');
$doc->addPage();
// SetFont + Cell, the FPDF way — but in points and with a real Unicode font.
$doc->setFont('DejaVuSans', 'B', 18.0);
$doc->setTextColor(30, 58, 138);
$doc->cell(0, 24.0, 'Quarterly Report', false, true, Alignment::Left);
$doc->setFont('DejaVuSans', '', 11.0);
$doc->setTextColor(0, 0, 0);
$doc->multiCell(0, 16.0, "Body text wraps on real font metrics. Unicode is "
. "native, so accented and non-Latin characters need no tFPDF variant — "
. "register the family in the fonts directory and select it by name.");
// Equivalent of $pdf->Output('D', 'report.pdf'):
$doc->output('report.pdf', OutputDestination::Download);
  • Unit. Setiap koordinat numerik, lebar, tinggi, dan margin yang Anda salin dari FPDF berada dalam milimeter secara default. Kalikan dengan 72 / 25.4 untuk mendapatkan point, sekali, selama port. Mencampur keduanya secara senyap salah-ukuran segalanya.
  • Urutan argumen Output(). FPDF adalah Output($dest, $name); NextPDF adalah output($name, $dest). Destinasinya adalah enum OutputDestination, bukan sebuah karakter. Utamakan save() / getPdfData() untuk keluaran file / string.
  • Urutan SetMargins. FPDF adalah (left, top, right); value object Margin NextPDF adalah (top, right, bottom, left). Urutkan ulang, jangan menyalin.
  • Fon. AddFont() + file metrik .php FPDF tidak punya padanan. Taruh file TrueType/OpenType di direktori fon dan panggil setFont() dengan nama keluarganya. Nama Base14 Core (Helvetica, Times, Courier) teresolusi tanpa sebuah file; di bawah PDF/A atau tagged PDF mereka disubstitusi otomatis dengan fon yang dapat ditanamkan.
  • GetStringWidth. Tidak ada metode pengukuran-string publik. Jika kode FPDF Anda mengukur string untuk menata kolom secara manual, alihkan blok itu ke multiCell() (yang wrap pada metrik) atau pemanggilan cell() lebar-tetap.

NextPDF memancarkan konten dalam satu lintasan streaming (architecture decision record ADR-001); memori puncak melacak ukuran dokumen, bukan pohon objek yang dipertahankan. Anggaran untuk contoh panduan ini adalah wall_ms: 2000, peak_mb: 128. Untuk dokumen panjang, gerakkan konten lintas pemanggilan addPage() — bentuk loop yang sama yang sudah digunakan sebuah laporan FPDF.

  • Metadata. SetTitle()/SetAuthor() memetakan ke setter bertipe yang menulis information dictionary / XMP ISO 32000-2 §14. Jangan pernah menyimpan secret di sana.
  • Path gambar. image() menolak skema stream-wrapper dan byte NUL yang ditanamkan sebelum membaca. Berikan path yang dikendalikan aplikasi.
  • Tanpa kode dalam-dokumen. NextPDF tidak mengeksekusi skrip dalam-dokumen apa pun; tidak ada di FPDF yang mengubah itu.
PernyataanSpecKlausa
Format/orientasi halaman memetakan ke kotak batas halaman.ISO 32000-2§7
Fon ditulis sebagai program fon ditanamkan/subset.ISO 32000-2§9
Judul / metadata mendarat di info dictionary / XMP.ISO 32000-2§14
Garis, persegi panjang, dan gambar adalah painting content-stream.ISO 32000-2§8

NextPDF menghasilkan konten ISO 32000-2; ia tidak menegaskan identitas visual dengan FPDF. Tinjau ulang keluaran kapan pun Anda mengubah renderer.

Tidak berlaku. NextPDF core mencakup jalur migrasi FPDF yang dijelaskan di sini.


Tim yang menjalankan FPDF (atau tFPDF) untuk generasi PDF sisi-server, prosedural. Jika kode Anda adalah sebuah urutan pemanggilan AddPage / SetFont / Cell / MultiCell / Image / Output yang digerakkan oleh SetXY dan Ln, maka pemetaan verb mencakup seluruh permukaan Anda.

Dalam lingkup: verb penggambaran FPDF, model kursor, fon, warna, garis dan persegi panjang, metadata, dan keluaran. Di luar lingkup: tooling file-metrik AddFont FPDF dan ekstensi-skrip FPDF pihak ketiga (barcode, rotasi, bookmark) — petakan itu ke modul NextPDF yang sesuai (Barcode, Transforms, Navigation), yang tidak dibahas di sini.

Kompatibilitas perilaku, bukan shim drop-in: core tidak menyediakan shim kelas FPDF. Tulis ulang setiap call site. Verb-verbnya berjajar dengan rapat karena API cell/text NextPDF berbagi garis keturunan FPDF/TCPDF, tetapi model unit, urutan argumen Output, dan tipe Margin/enum berbeda — jadi sebuah transkripsi salah, sebuah terjemahan benar.

Konstruk FPDFNextPDFCatatan
$unit ('mm' default)(tidak ada padanan)Bekerja dalam PDF point. Konversi dimensi dengan pt = mm * 72 / 25.4 sekali selama port.
$orientation ('P'/'L')enum Orientation pada addPage(), atau tukar lebar/tinggi PageSizeLandscape = lebar > tinggi.
$size ('A4', [w,h])Config->pageSize (value object PageSize)Format bernama menjadi dimensi point eksplisit; factory PageSize::A4()A0() dan Letter/Legal ada.
SetMargins($l, $t, $r)Config->margins (Margin VO)Urutan constructor (top, right, bottom, left).
AddFont($family, $style, $file)direktori fon + setFont() berdasarkan namaBuang file metrik; tempatkan TTF/OTF di Config->fontsDirectory.
  • Direktori fon. Registrasi AddFont per-fon FPDF menyusut menjadi sebuah direktori fon ditambah pencocokan keluarga setFont(). Mulai dengan Config->fontsDirectory (path pencarian default); daftarkan direktori tambahan via FontRegistry::addFontDirectory() atau Document::addFontDirectory() ketika fon berada di lebih dari satu tempat.
  • Selalu Unicode. Tidak ada default Latin-1 dan tidak ada build tFPDF terpisah; input UTF-8 adalah normanya.
  • Selalu subset. NextPDF selalu men-subset fon yang ditanamkan (ISO 32000-2 §9); pilihan penanaman-fon FPDF tidak punya padanan dan tidak diperlukan.
  • Re-baseline glyph. Pencocokan dan fallback fon bersifat engine-specific; sebuah alias fon FPDF mungkin membutuhkan nama keluarga persis. Perbedaan substitusi diharapkan, bukan cacat.
  • Konversi unit (mm → pt) — kesalahan porting paling umum; lihat di atas.
  • Urutan argumen Output bertukar dan destinasinya menjadi sebuah enum.
  • Margin / Alignment / Orientation adalah objek/enum bertipe, bukan karakter atau triple (l, t, r) posisional.
  • Tanpa GetStringWidth publik — gerakkan wrapping melalui multiCell().
  • Rasterisasi independen — wrap baris dan paginasi pada konten padat dapat berbeda; re-baseline diff visual.

Ini adalah perbedaan perilaku terdokumentasi, bukan cacat di salah satu engine.

  • Selektor $unit FPDF — tidak dimodelkan (selalu point).
  • File metrik AddFont() + .php/.z — digantikan oleh sebuah direktori fon.
  • GetStringWidth() — tidak ada verb pengukuran-string publik.
  • Karakter destinasi 'I'/'D'/'F'/'S' FPDF — digantikan oleh enum OutputDestination + save()/getPdfData().

Kode yang bergantung pada ini tidak “bermigrasi” verbatim. Ekspresikan ulang dengan baris-baris di atas.

  1. Tambahkan nextpdf/core di samping FPDF; pertahankan FPDF terpasang untuk sekarang.
  2. Pilih satu dokumen berisiko-rendah. Konversi constructor via peta unit, lalu port setiap verb dengan peta verb. Konversi setiap koordinat mm ke point.
  3. Tempatkan fon dokumen di Config->fontsDirectory dan pilih berdasarkan nama keluarga; buang pemanggilan AddFont.
  4. Hasilkan kedua PDF untuk input yang sama dan diff secara visual. Perbedaan (substitusi fon, wrap baris) diharapkan untuk engine independen — terima per dokumen.
  5. Ganti setiap tata-letak-manual berbasis GetStringWidth dengan multiCell() atau pemanggilan cell() lebar-tetap.
  6. Ulangi per dokumen, berisiko-terendah lebih dulu; pertahankan FPDF terpasang sampai cutover terakhir.
  7. Hapus FPDF dari composer.json setelah cutover final.
  • Snapshot keluaran FPDF untuk dokumen representatif sebelum Anda mengubah kode (input golden; byte-nya akan berbeda).
  • Untuk setiap dokumen yang dimigrasikan, tegaskan penerimaan dengan pemeriksaan Anda sendiri (diff visual + ekstraksi-teks). Perilaku cell/fon NextPDF dijalankan oleh examples/04-text-and-fonts.php ditambah suite Font dan text-output tests/ core. Penerimaan migrasi bersifat dokumen-spesifik dan tetap menjadi tanggung jawab Anda.
  • Tambahkan sebuah tes regresi per dokumen yang dimigrasikan.

Setiap pernyataan perilaku NextPDF di halaman ini didukung oleh tanda tangan kode sumber dalam-repo, contoh, atau architecture decision record (ADR), atau, untuk properti format-PDF, oleh klausa ISO 32000-2 di frontmatter citations: dan tabel Conformance. Perilaku FPDF ditegaskan hanya sebagai “engine independen — harapkan perbedaan terdokumentasi”; halaman ini tidak mengklaim paritas yang tidak dibuktikan oleh sebuah artefak dalam-repo.

Klaim perilaku NextPDFBukti dalam-repo (path)
AddPage memetakan ke addPage(?PageSize, Orientation): static.src/Core/Concerns/HasPages.php (addPage()).
SetFont($family, $style, $size) memetakan ke setFont(string, string, float): static; style ''/'B'/'I'/'BI'/'U'.src/Core/Concerns/HasTypography.php (setFont()).
Cell memetakan ke cell($w, $h, $txt, $border, $newLine, $align, $fill): static.src/Core/Concerns/HasTextOutput.php (cell()).
MultiCell memetakan ke multiCell($w, $h, $txt, $border, $align): static (wrap berbasis-metrik).src/Core/Concerns/HasTextOutput.php (multiCell(), wrapText()).
Write/Text/Ln memetakan ke write()/text()/ln().src/Core/Concerns/HasTextOutput.php (write(), text(), ln()).
SetXY/SetX/SetY/GetX/GetY memetakan langsung; SetMargins menerima sebuah Margin VO.src/Core/Concerns/HasPages.php (setXY(), getX(), setMargins()); src/ValueObjects/Margin.php ((top, right, bottom, left)).
Image memetakan ke image($file, ?$x, ?$y, ?$w, ?$h): static; menolak path skema/NUL.src/Core/Concerns/HasImages.php (image(), assertImageFilePath()).
Line/Rect/SetLineWidth/SetDrawColor/SetFillColor/SetTextColor memetakan langsung.src/Core/Concerns/HasDrawing.php (line(), rect(), setLineWidth()); src/Core/Concerns/HasColors.php (setDrawColor(), setFillColor(), setTextColor()).
Halaman default createStandalone() adalah A4 portrait (595.276 × 841.890 pt).src/Core/Document.php (createStandalone()); src/ValueObjects/PageSize.php (A4()).
Destinasi keluaran adalah enum OutputDestination (Inline/Download/File/String); Output('S')getPdfData(), Output('F', $p)save($p).src/Contracts/OutputDestination.php; src/Core/Concerns/HasOutput.php (output()).
SetTitle/SetAuthor/… memetakan ke setter metadata bertipe; mendarat di info dictionary / XMP.src/Core/Concerns/HasMetadata.php (setTitle(), setAuthor()); ISO 32000-2 §14 (frontmatter citations:).
Fon selalu ditanamkan sebagai program subset.src/Core/Concerns/HasTypography.php (buildFontData()); ISO 32000-2 §9 (frontmatter citations:).
Konten dipancarkan satu-lintasan.docs/architecture/adr/ADR-001-stream-based-rendering-pipeline.md.

Kedua paket tetap terpasang sampai cutover final, sehingga rollback per-call-site berarti mengembalikan call site itu ke jalur FPDF. Setelah cutover final, rollback berarti memulihkan FPDF dan kode sebelumnya dari version control. Tidak ada migrasi data yang terlibat.

Lihat Performa. Model satu-lintasan menghapus biaya buffer yang dipertahankan. Biaya per-dokumen yang baru adalah resolusi fon yang eager (langkah 3), yang dapat di-cache melalui direktori fon.

  • Menyalin koordinat milimeter sebagai point tanpa konversi * 72 / 25.4.
  • Membiarkan Output() dalam urutan ($dest, $name) FPDF, atau memberikan sebuah karakter alih-alih enum OutputDestination.
  • Menyalin SetMargins($l, $t, $r) langsung ke dalam Margin (yang urutannya top, right, bottom, left).
  • Mengharapkan file metrik AddFont diport; tempatkan TTF/OTF di direktori fon sebagai gantinya.
  • Mencari padanan GetStringWidth; gunakan multiCell() untuk wrapping.
  • Mengharapkan keluaran identik-byte/piksel (engine independen — panduan ini tidak pernah mengklaim drop-in atau kompatibilitas 100%).