Bermigrasi dari pustaka lama: TCPDF, FPDF, dan kawan-kawan

SpecSpec: ISO 32000-2ISO 32000-2SpecSpec: ISO 19005-4ISO 19005-4SpecSpec: ETSI EN 319 142-1ETSI EN 319 142-1

Sekilas pandang

Jika PDF Anda dihasilkan oleh TCPDF, FPDF, mPDF, atau dompdf, kodenya mungkin masih berfungsi. Justru itulah sebabnya masalahnya mudah luput. Pustaka berjalan, berkasnya terbuka, dan celahnya baru muncul pada hari seseorang meminta dokumen yang ditandatangani, dapat diarsipkan, atau dapat diakses, dan jawabannya adalah “kami tidak bisa dari sini.”

Halaman ini adalah kisah migrasinya: apa saja tembok itu, mengapa ia bersifat struktural alih-alih kebetulan, dan bagaimana NextPDF memberi Anda jalan bertahap untuk lepas darinya — termasuk permukaan kompatibilitas TCPDF yang merupakan alat bantu migrasi, bukan janji pengganti langsung yang identik byte demi byte.

Mengapa ini penting

Pustaka PDF bukanlah pemanggilan render yang Anda lakukan sekali saja. Ia adalah dependensi yang diwarisi dokumen Anda selama dokumen itu ada. Ketika dependensi itu berhenti bergerak, dokumen Anda berhenti mampu melakukan hal-hal baru — dan Anda baru menyadarinya pada saat yang paling buruk, ketika seorang pelanggan, auditor, atau regulator menetapkan standarnya.

Temboknya tampak seperti ini. Formatnya bergerak maju: PDF 2.0 adalah edisi standar saat ini (SpecSpec: ISO 32000-2ISO 32000-2), dan penulis yang terjebak pada struktur 1.x tertinggal di belakang format yang diasumsikan oleh seluruh toolchain Anda. Penandatanganan tipis atau hanya ditempelkan, jauh dari profil baseline PAdES yang membuat sebuah tanda tangan bertahan (SpecSpec: ETSI EN 319 142-1, §4ETSI EN 319 142-1 §4). Keluaran arsip ke keluarga PDF/A, dan struktur bertag untuk aksesibilitas, entah absen atau rapuh. Dan API-nya sendiri tanpa tipe — orientasi berupa string, boolean posisional, nilai default yang Anda temukan secara tidak sengaja — sehingga kompiler tidak dapat membantu Anda, dan begitu pula peninjau.

Tidak ada satu pun dari semua ini yang merupakan bug yang bisa Anda tambal. Itu adalah bentuk dari alat yang dibangun untuk dekade sebelumnya, dan beberapa di antaranya tidak lagi aktif bergerak menuju standar yang kini harus dipenuhi dokumen Anda.

Versi singkatnya

• Pustaka PDF PHP lama umumnya masih berjalan. Masalahnya adalah apa yang umumnya tidak dapat mereka hasilkan dengan konformitas modern penuh: PDF 2.0, tanda tangan yang konform-baseline, PDF/A tervalidasi, aksesibilitas bertag — dukungan pada pustaka-pustaka yang disebut terbatas atau absen.
• NextPDF adalah mesin PHP 8.4 yang menulis PDF 2.0 secara default, dengan tipe ketat, profil arsip, dan penandatanganan PAdES sebagai keluaran kelas satu.
• Anda tidak harus menulis ulang segalanya pada hari pertama. Permukaan kompatibilitas TCPDF membuat pemanggilan yang sudah dikenal tetap berfungsi selagi Anda memindahkan logika dokumen yang penting.
• Permukaan itu kompatibel dengan, bukan identik byte demi byte dengan TCPDF. Ia adalah jembatan melintasi migrasi, dengan perbedaan perilaku yang terdokumentasi — bukan klaim bahwa setiap skrip berjalan tanpa perubahan.
• Uji yang jujur adalah apakah kemampuan baru itu sepadan dengan perpindahannya. Untuk sebagian beban kerja tidak demikian, dan kami mengatakannya secara terus terang.

Bagaimana NextPDF menanganinya

Pendekatannya adalah menjadikan migrasi sebuah urutan, bukan lompatan. Anda terus menghasilkan dokumen sepanjang jalan, dan Anda menukar kendala lama satu per satu alih-alih mempertaruhkan sebuah rilis pada penulisan ulang sekaligus.

1. InventoryCatalogue what your documents actually need to emit — signatures, archival profiles, tagged structure, fonts — not just which calls you make today.
2. BridgeAdopt the TCPDF-compatibility surface so the existing call sites keep producing files while the engine underneath becomes NextPDF.
3. PortMove the document logic that matters onto the native typed API, where intent is explicit and the compiler checks it.
4. UpgradeTurn on the outputs many legacy libraries cannot reach with full modern conformance: PDF 2.0 structure, validated PDF/A, PAdES signatures, tagged accessibility.
5. VerifyConfirm the result against a real validator, so 'archival' or 'signed' means a tool agrees, not just that the file opened.

A staged migration off a legacy PDF library: start on the compatibility surface so existing calls keep working, then move document logic onto the typed native API, then turn on the standards-grade outputs (PDF 2.0, PDF/A, PAdES, accessibility) that many legacy libraries cannot produce with full modern conformance.

PDF 2.0 adalah baseline, bukan tanda fitur. NextPDF menulis edisi format saat ini secara default (SpecSpec: ISO 32000-2ISO 32000-2), dan dapat menserialkan struktur yang lebih lama ketika sebuah profil memintanya. Pustaka yang membeku pada struktur 1.x tidak dapat menemui Anda di sini; ini bukan pengaturan yang terlewat, ini adalah era yang mendahuluinya.

Arsip dan aksesibilitas adalah properti penulis. Menghasilkan berkas yang diterima validator sebagai PDF/A adalah sesuatu yang harus dilakukan mesin saat ia menulis — ia tidak dapat ditempelkan setelahnya (SpecSpec: ISO 19005-4ISO 19005-4). Hal yang sama berlaku untuk struktur bertag yang membuat sebuah PDF dapat diakses. NextPDF membangun ini selama pembuatan, yang justru merupakan langkah yang tidak dapat diambil banyak alat lama — atau hanya sebagian, kurang dari yang diterima validator.

Penandatanganan melewati standar baseline. Tanda tangan elektronik tingkat lanjut dalam sebuah PDF mengikuti profil PAdES (SpecSpec: ETSI EN 319 142-1, §4ETSI EN 319 142-1 §4), tempat digest mencakup rentang byte yang dideklarasikan dan tanda tangan membawa metadata yang diperiksa validator. Pembantu penandatanganan tempelan jarang mencapai standar itu. NextPDF memperlakukannya sebagai keluaran kelas satu, bukan renungan belakangan.

Permukaan kompatibilitas adalah jembatannya, dinyatakan secara jujur. Lapisan TCPDF-compat ada agar lokasi pemanggilan Anda yang sudah ada tetap menghasilkan dokumen selagi Anda memigrasikan bagian-bagian yang penting. Ia mengikuti model yang sama seperti setiap panduan migrasi NextPDF: kompatibel dengan pustaka sumber, bukan identik byte demi byte, dengan perbedaan perilaku yang dituliskan. Kejujuran itulah intinya — klaim diam-diam “99% pengganti langsung” adalah jenis tebakan yang dirancang untuk ditolak oleh mesin ini.

Human-factors note:Human-factors note

Alasan untuk bermigrasi jarang berupa kode yang Anda miliki hari ini; melainkan dokumen yang akan diminta dari Anda esok hari. Maintainability adalah properti kualitas yang bernama — seberapa siap sebuah sistem dapat dianalisis dan diubah seiring kebutuhan berganti (SpecSpec: ISO/IEC 25010, §3.6ISO/IEC 25010 §3.6). Dependensi yang telah berhenti bergerak diam-diam mengikisnya, dan Anda baru merasakan biayanya ketika sebuah persyaratan baru tiba dan jawabannya harus “tidak dari sini.” Perpindahan bertahap membayar biaya itu sesuai jadwal Anda, selagi dokumen tetap mengalir, alih-alih sekaligus di bawah tenggat.

Contoh praktis

Bentuk sebuah migrasi kecil di lokasi pemanggilan. Kode lama tetap menghasilkan sebuah berkas melalui permukaan kompatibilitas; kode baru menyatakan maksud melalui API native bertipe dan meminta keluaran yang tidak dapat dicapai pustaka lama, atau hanya dicapai dengan konformitas terbatas.

<?php

declare(strict_types=1);

use NextPDF\Compat\Tcpdf\TCPDF;
use NextPDF\Contracts\Orientation;
use NextPDF\Contracts\OutputDestination;
use NextPDF\Core\Document;
use NextPDF\ValueObjects\PageSize;

// 1) The bridge: a familiar TCPDF-shaped call keeps producing a file
//    while the engine underneath is already NextPDF. Behaviour is
//    compatible, not byte-identical — differences are documented.
$legacy = new TCPDF();
$legacy->AddPage();
$legacy->SetFont('helvetica', 'B', 16);
$legacy->Cell(0, 12, 'Migrated invoice', ln: 1);
$bridgedBytes = $legacy->Output('', 'S');

// 2) The destination: the same document expressed natively, where intent
//    is typed and the engine can emit what many legacy tools cannot.
$document = Document::createStandalone();
$document->setTitle('Migrated invoice');
$document->addPage(PageSize::a4(), Orientation::Portrait);
$document->setFont('helvetica', 'B', 16);
$document->cell(0, 12, 'Migrated invoice', newLine: true);

// Bytes only, no HTTP headers, no file side effect — stated, not inferred.
$nativeBytes = $document->output(dest: OutputDestination::String);

Blok pertama adalah pijakan: tidak ada apa pun di aplikasi Anda yang harus berubah agar dokumen tetap mengalir. Yang kedua adalah tujuannya: pemanggilan bertipe yang “portrait”, “keluaran string”, dan fontnya eksplisit, dan tempat arsip, penandatanganan, serta aksesibilitas menjadi keluaran yang dapat Anda aktifkan alih-alih tembok yang Anda tabrak.

Kesalahpahaman umum

Harapan yang sering muncul adalah “pasti ada tanda yang membuat pustaka lama saya mendukung PDF 2.0 dan tanda tangan.” Tidak ada. Ini bukan opsi yang lupa diekspos oleh pustaka yang matang; ini adalah kemampuan yang arsitekturnya memang tidak pernah dibangun untuk itu. Anda tidak bisa mengonfigurasi diri menuju sebuah edisi format atau profil tanda tangan yang tidak diimplementasikan oleh sebuah penulis.

Kesalahpahaman cerminannya adalah bahwa NextPDF adalah pengganti langsung TCPDF 100%, sehingga migrasi itu gratis. Tidak demikian, dan kami tidak akan berpura-pura sebaliknya. Permukaan kompatibilitas mencakup irisan API yang nyata dan terdokumentasi untuk membawa Anda melintasi perpindahan; beberapa pemanggilan berperilaku berbeda, dan sedikit yang berada di luar cakupan. Perlakukan ia sebagai jembatan dengan peta yang diterbitkan, bukan jaminan bahwa setiap skrip lama berjalan tanpa disentuh.

Batas dan batasan

TCPDF-compatibility surface as a migration aid — edition availability

Edition	Availability
Core	○ The compatibility surface is compatible with, not byte-identical to TCPDF. It covers a documented subset of the API to keep existing call sites producing files during migration. It is a bridge, not a drop-in: some behaviours differ and some calls are unsupported, all listed in the method-coverage and migration pages. The destination is the native typed API, where standards-grade output lives.
Pro	●Available
Enterprise	●Available

Migrasi adalah sarana, bukan kebajikan. Jika dokumen Anda sederhana, pustaka Anda masih terpelihara, dan Anda tidak akan pernah membutuhkan PDF 2.0, penandatanganan, PDF/A, atau aksesibilitas, jawaban yang jujur mungkin adalah tetap di tempat Anda berada — biaya peralihan itu nyata dan perpindahan yang tidak Anda butuhkan adalah perpindahan yang tidak seharusnya Anda lakukan. Halaman tentang kapan tidak menggunakan NextPDF menarik garis itu tanpa ragu.

Halaman ini menjelaskan jalur migrasi dan target mesin. Cakupan API yang persis, perbedaan perilaku, dan prosedur langkah demi langkah ada di dokumentasi kompatibilitas, yang merupakan otoritas atas apa yang dilakukan tiap pemanggilan. Tidak ada apa pun di sini yang menjanjikan bahwa skrip lama sembarangan berjalan tanpa perubahan.

Dokumen terkait

• What PDF 2.0 changed — edisi format yang tidak dapat dipancarkan banyak pustaka lama, dan mengapa itu penting.
• The TCPDF compatibility surface — panduan otoritatif tentang apa yang dicakup jembatan dan di mana ia berbeda.
• When not to use NextPDF — batas yang jujur, agar migrasi yang tidak Anda butuhkan adalah migrasi yang dapat Anda lewati.
• One engine, every framework — tempat mesin yang Anda tuju terpasang ke dalam tumpukan yang sudah Anda jalankan.

Glosarium

• PDF 2.0 — edisi standar Portable Document Format saat ini (ISO 32000-2). Diuraikan saat pertama disebut; format yang ditulis NextPDF secara default.
• PDF/A — keluarga konformitas arsip (seri ISO 19005) yang mendefinisikan apa yang membuat sebuah PDF aman dipreservasi dalam jangka panjang. Sebuah properti yang harus dihasilkan penulis, bukan yang bisa ditambahkan pemanggil belakangan.
• PAdES — PDF Advanced Electronic Signatures, keluarga profil ETSI (EN 319 142) untuk menyematkan tanda tangan kelas standar dalam sebuah PDF. Diuraikan saat pertama disebut; dibahas secara mendalam pada halaman penandatanganan.
• Permukaan kompatibilitas — lapisan API yang berbentuk seperti pustaka sumber (di sini, TCPDF) yang membuat lokasi pemanggilan yang ada tetap berfungsi selama migrasi. Kompatibel dengan, bukan identik byte demi byte dengan, aslinya — sebuah jembatan, bukan pengganti langsung.
• Pengganti langsung (drop-in replacement) — pengganti yang menjalankan kode yang ada tanpa perubahan. Permukaan TCPDF-compat sengaja tidak dijelaskan dengan cara ini; ia adalah alat bantu migrasi terdokumentasi dengan perbedaan perilaku yang diketahui.