Cakupan metode TCPDF pada NextPDF compat-legacy
Sekilas pandang
Bagian berjudul “Sekilas pandang”nextpdf/compat-legacy adalah lapisan kompatibilitas, bukan fork TCPDF ataupun klon perilaku yang dijamin sama. Lapisan ini mengekspos nama metode publik, urutan parameter, dan nilai standar TCPDF 6.x di atas mesin inti NextPDF. Sebagian besar panggilan dipetakan langsung ke satu operasi NextPDF Document. Sebagian kecil metode menerima parameter lawas yang tidak dipakai oleh NextPDF, atau memang tidak berpengaruh.
Halaman ini menyajikan ringkasan audit per metode untuk pembaca. Matriks cakupan yang otoritatif dan terverifikasi oleh pengujian berada di repositori pada docs/TCPDF_COVERAGE.md. Jika halaman ini dan matriks di dalam repositori bertentangan, matriks di dalam repositori yang berlaku karena rangkaian pengujian menegaskannya.
Gunakan halaman ini untuk menjawab satu pertanyaan sebelum Anda bermigrasi: untuk setiap metode TCPDF yang dipanggil oleh basis kode Anda, apa yang sebenarnya dilakukan adaptor?
Ringkasan cakupan
Bagian berjudul “Ringkasan cakupan”Audit ini memeriksa sekitar 120 metode publik TCPDF 6.x. Setiap metode ditempatkan tepat dalam salah satu dari empat kategori.
| Kategori | Jumlah | Apa artinya bagi Anda |
|---|---|---|
| Dicerminkan — didelegasikan penuh | 94 | Panggilan dipetakan langsung ke satu metode NextPDF Document. Perilakunya kompatibel untuk parameter yang terdokumentasi. |
| Diabaikan diam-diam — sebagian | 15 | Metode berjalan dan menghasilkan keluaran, tetapi satu atau lebih parameter TCPDF tidak berpengaruh. Ini adalah perbedaan perilaku yang terdokumentasi. |
| Belum diimplementasikan — badan no-op | 4 | Metode ada demi kompatibilitas sumber tetapi tidak melakukan apa pun. |
| Tidak berlaku | 7 | Metode TCPDF tidak berpengaruh pada keluaran PDF; sengaja dikecualikan. |
| Metode drift API modern yang ditambahkan | 17 | Metode Document NextPDF v5.1+ yang diekspos pada adaptor sehingga kode dengan API campuran tetap dapat dikompilasi. Metode ini tidak memiliki padanan di TCPDF 6.x. |
Angka-angka ini berasal dari docs/TCPDF_COVERAGE.md §Summary. Rangkaian pengujian memverifikasi matriks melalui tests/Unit/Compat/Tcpdf/TcpdfApiDriftTest.php dan tests/Unit/Compat/Tcpdf/TcpdfStrictModeTest.php.
Catatan istilah. Paket ini tidak mengklaim sebagai “pengganti langsung (drop-in replacement)” atau “kompatibel dengan TCPDF (bukan identik per byte)”. Paket ini mencakup 94 dari ~120 metode TCPDF yang disurvei melalui delegasi langsung. Metode sisanya memiliki perbedaan perilaku yang terdokumentasi, dijelaskan di bawah. Deskripsi yang akurat adalah alternatif yang kompatibel dengan TCPDF dengan permukaan kompatibilitas yang diketahui dan teruji.
Catatan tentang penghitungan metode
Bagian berjudul “Catatan tentang penghitungan metode”Adaptor dibangun dari 25 trait concern dengan tanggung jawab tunggal (src/Compat/Tcpdf/Concerns/) yang mengekspos total 273 metode publik, ditambah sejumlah kecil metode siklus hidup dan escape-hatch pada kelas TCPDF itu sendiri. Kategori cakupan di atas menghitung metode berbeda pada permukaan API TCPDF 6.x (~120), bukan total jumlah metode publik adaptor. Kedua angka itu mengukur hal yang berbeda: cakupan permukaan API dan ukuran implementasi. Jika README.md paket menyebut jumlah trait atau jumlah metode yang lebih kecil, perlakukan docs/TCPDF_COVERAGE.md dan halaman ini sebagai otoritatif. Ringkasan README ditulis sebelum trait AdaptsDriftV51.
1. Metode yang dicerminkan — delegasi yang kompatibel
Bagian berjudul “1. Metode yang dicerminkan — delegasi yang kompatibel”Sembilan puluh empat metode dipetakan langsung ke instance NextPDF\Core\Document yang mendasarinya. Nama PascalCase TCPDF dipetakan ke nama camelCase NextPDF jika mesin menggunakan camelCase. Adaptor menerima kedua ejaan untuk kompatibilitas maju dan mundur.
Kelompok representatif (tabel lengkap: docs/TCPDF_COVERAGE.md §1):
| Area TCPDF | Contoh metode | Trait adaptor |
|---|---|---|
| Siklus hidup | Output(), Close(), getPDFData() | AdaptsLifecycle |
| Halaman | AddPage(), getNumPages(), deletePage() | AdaptsPageManagement |
| Teks | Cell(), MultiCell(), Write(), Text(), Ln() | AdaptsTextOutput |
| Fon | SetFont(), SetFontSize(), AddFont() | AdaptsFonts |
| Warna | SetTextColor(), SetDrawColor(), SetFillColor() | AdaptsColors |
| Penggambaran | Line(), Rect(), Circle(), Polygon(), Arrow() | AdaptsDrawing |
| Transformasi | Rotate(), Scale(), Translate(), Skew(), Mirror*() | AdaptsTransforms |
| Navigasi | AddLink(), Annotation(), addTOC() | AdaptsNavigation |
Untuk metode-metode ini, perilaku yang teramati kompatibel dengan TCPDF 6.x untuk parameter yang didokumentasikan oleh NextPDF. Adaptor tidak menjamin keluaran PDF yang identik byte demi byte. Mesin yang mendasarinya adalah implementasi PDF 2.0 independen, sehingga byte dapat berbeda meski hasil yang terlihat setara. Jika pengujian Anda menegaskan byte PDF yang persis, bukan konten yang dirender, bersiaplah untuk membuat ulang baseline pengujian tersebut. Lihat /integrations/tcpdf-compat/migration/ untuk strategi pembuatan ulang baseline yang direkomendasikan.
2. Metode yang diabaikan diam-diam — perbedaan perilaku yang terdokumentasi
Bagian berjudul “2. Metode yang diabaikan diam-diam — perbedaan perilaku yang terdokumentasi”Ke-15 metode ini berjalan dan menghasilkan keluaran, tetapi setidaknya satu parameter TCPDF diterima demi kompatibilitas sumber lalu diabaikan. Baca bagian ini sebelum Anda bermigrasi. Panggilan ini tidak gagal; secara diam-diam, perilakunya lebih terbatas daripada TCPDF asli.
| Metode TCPDF | Parameter yang diabaikan | Alternatif yang kompatibel |
|---|---|---|
Image() | type, link, align, resize, dpi, palign, ismask, imgmask, border, fitbox, hidden, fitonpage, alt, altimgs | NextPDF image() menerima file, x, y, width, height. Untuk gambar yang dapat diklik, gambar citranya terlebih dahulu, lalu tambahkan Document::link() di atas persegi panjang yang sama. Masking gambar dan gambar alternatif tidak didukung. |
writeHTML() | ln, fill, reseth, cell, align | NextPDF writeHtml() hanya untuk konten. Bungkus HTML dalam blok yang diposisikan melalui API modern untuk kontrol tata letak. |
writeHTMLCell() | border (string form), ln, fill, reseth, autopadding | Lebar, tinggi, posisi, dan border boolean dihormati; tata letak sel yang lebih kaya tidak punya pemetaan. |
ImageEps() | link, useBoundingBox, align, palign, border, fitonpage, fixoutvals | Hanya posisi dan ukuran. |
ImageSVG() | link, align, palign, border, fitonpage | Hanya posisi dan ukuran. |
SetProtection() | mode (non-zero), pubkeys (non-empty) | NextPDF selalu menggunakan AES-256 untuk handler standar. Untuk enkripsi berbasis sertifikat, gunakan setPublicKeyEncryption() modern yang diekspos pada adaptor (lihat /integrations/tcpdf-compat/security-and-operations/). |
Bookmark() | style, color, x, isNamedDest | Judul, level, dan posisi-y dihormati. |
setDestination() | page, x | Nama dan posisi-y dihormati. |
Link() | spaces | Pelacakan spasi-putih internal TCPDF; tidak ada padanannya di mesin. |
Annotation() | kunci opsi selain Subtype, spaces | Tipe, posisi, dan teks dihormati. |
SetLineStyle() | detail pola garis putus-putus selain width | Properti garis inti dipetakan. |
setAlpha() | peta mode blend yang parsial | Beberapa nama mode blend tidak memiliki padanan di mesin. |
Polycurve() | seluruh daftar parameter | No-op dalam mode standar; tidak ada padanan di mesin. |
PieSectorXY() | seluruh daftar parameter | Pemetaan parsial (garis dari pusat ke tepi berbeda). |
RoundedRectXY() | radius per sudut | Hanya radius sudut yang seragam. |
Cara adaptor memunculkan perbedaan ini bergantung pada mode ketat (lihat /integrations/tcpdf-compat/configuration/). Dengan mode ketat nonaktif, yaitu setelan standar yang kompatibel mundur, panggilan ini terdegradasi secara diam-diam. Dengan mode ketat aktif, setiap panggilan yang mengabaikan parameter melempar TcpdfNotImplementedException berisi daftar parameter yang diabaikan secara persis dan petunjuk migrasi. Mode ketat adalah alat audit, bukan setelan produksi.
Desain mode ketat mengikuti prinsip bahwa pemanggil harus mampu mengamati ketika maksudnya tidak dipenuhi. OWASP ASVS 5.0 §16.5.3 menyatakan bahwa aplikasi harus gagal dengan baik dan aman serta mencegah kondisi fail-open. Hilangnya parameter secara diam-diam adalah jebakan pengalaman pengembang, bukan kerentanan, tetapi prinsip gagal secara eksplisit yang sama tetap berlaku. Ringkasan klausul yang dicantumkan ada di
citationsdi frontmatter halaman.
3. Metode yang belum diimplementasikan — badan no-op
Bagian berjudul “3. Metode yang belum diimplementasikan — badan no-op”Empat metode ada agar sumber lawas dapat dikompilasi, tetapi badannya tidak melakukan apa pun. Dengan mode ketat aktif, tiga di antaranya melempar TcpdfNotImplementedException. Yang keempat (Open()) adalah no-op aman yang disengaja dan tidak pernah melempar, karena Anda selalu dapat menghapusnya dari kode lawas dengan aman.
| Metode TCPDF | Perilaku | Pengganti |
|---|---|---|
setSignature() | No-op (tidak menyimpan data apa pun yang dapat ditindaklanjuti). Melempar dalam mode ketat. | Penandatanganan digital memerlukan edisi NextPDF komersial. Gunakan API tanda tangan modern dengan objek nilai CertificateInfo; lihat /integrations/tcpdf-compat/security-and-operations/. |
addEmptySignatureAppearance() | No-op. Melempar dalam mode ketat. | Pembatasan edisi komersial yang sama seperti setSignature(). |
endPage() | No-op. Melempar dalam mode ketat. | NextPDF mengelola siklus hidup halaman secara otomatis. Hapus panggilan tersebut. |
Open() | No-op aman. Tidak pernah melempar. | NextPDF membuka dokumen secara otomatis. Menghapus panggilan tersebut selalu aman. |
Penandatanganan tidak tersedia di mesin inti melalui adaptor ini. Adaptor mengekspos titik masuk tanda tangan modern yang mendelegasikan ke mesin. Dukungan tanda tangan baseline dibatasi pada edisi komersial. Dokumentasi ini tidak membuat klaim apa pun tentang profil tanda tangan validasi jangka panjang atau bertanda waktu untuk edisi mana pun. Lihat /integrations/tcpdf-compat/security-and-operations/ untuk pernyataan yang tepat dan konservatif.
4. Metode yang tidak berlaku
Bagian berjudul “4. Metode yang tidak berlaku”Tujuh metode TCPDF tidak berpengaruh pada keluaran PDF dan sengaja dikecualikan. Anda dapat memanggilnya dengan aman.
| Metode TCPDF | Alasan dikecualikan |
|---|---|
setDocCreationTimestamp() / setDocModificationTimestamp() | Status disimpan pada adaptor tetapi tidak tersambung ke metadata XMP dokumen. Tidak terlihat dalam keluaran. |
setSRGBmode() | Manajemen warna NextPDF tidak bergantung pada flag ini. |
setPDFVersion() | NextPDF memilih versi PDF dari profil conformance/output-nya; tidak ada setter langsung. Adaptor memunculkan notice lalu melanjutkan. |
setDocInfoUnicode() | NextPDF selalu Unicode; flag ini adalah no-op secara desain. |
setDefaultMonospacedFont() | Tidak ada padanan di mesin; penataan gaya HTML/CSS berlaku sebagai gantinya. |
setFontSubsetting() | NextPDF selalu melakukan subset terhadap fon yang disematkan; flag ini secara efektif selalu aktif. |
Versi PDF ditetapkan oleh mesin. Keluaran ditulis sebagai PDF 2.0 (ISO 32000-2). ISO 32000-2 §7.5.2 menetapkan bahwa penulis yang patuh mengidentifikasi versi dokumen, baik di header berkas maupun entri Version katalog, sebagai 2.0. Standar itu juga menetapkan bahwa menyimpan berkas tidak menurunkan versi berkas tersebut. Itu sesuai dengan perilaku adaptor: panggilan seperti setPDFVersion('1.4') tidak dapat diarahkan ke versi PDF yang lebih lama melalui adaptor ini. Ringkasan klausul yang dicantumkan ada di citations di frontmatter halaman.
5. Metode drift API modern
Bagian berjudul “5. Metode drift API modern”Tujuh belas metode dari inti NextPDF v5.1+ diekspos pada adaptor (trait AdaptsDriftV51) sehingga kode yang mencampur API TCPDF dengan API modern tetap dapat dikompilasi. Metode ini tidak memiliki padanan di TCPDF 6.x. Contoh: getWarnings(), hasWarnings(), embedFileFromString(), enableBiDi(), beginTag() / endTag(), enableLinearization(), useAesGcm(), useDocumentMac(), setConformanceMode(). Perlakukan metode ini sebagai API modern, bukan sebagai bagian dari kontrak kompatibilitas TCPDF.
6. Panduan penghentian dan penggantian
Bagian berjudul “6. Panduan penghentian dan penggantian”| Jika kode Anda memanggil… | Status | Lakukan ini sebagai gantinya |
|---|---|---|
Error() | Perilaku berubah (diperketat) | Adaptor mengganti die() milik TCPDF dengan RuntimeException yang dilempar. Bungkus panggilan berisiko dengan try/catch; jangan mengandalkan terminasi proses. |
setPDFVersion() | Tidak berlaku | Hapus. Keluaran selalu PDF 2.0. |
setUserRights() | Tidak digunakan lagi di PDF 2.0 | Hapus. Panggilan tersebut memunculkan notice E_USER_DEPRECATED dan diabaikan. |
setSignature() | Belum diimplementasikan di inti | Migrasikan ke API tanda tangan modern pada edisi komersial. |
Image(...) dengan parameter tambahan | Diabaikan diam-diam | Kurangi menjadi file, x, y, w, h; tambahkan Document::link() untuk gambar yang dapat diklik. |
endPage() / Open() | Belum diimplementasikan / no-op | Hapus. |
7. Langkah migrasi yang aman
Bagian berjudul “7. Langkah migrasi yang aman”- Pasang paket dan jalankan rangkaian pengujian Anda yang sudah ada terhadap adaptor tanpa perubahan kode. Lihat /integrations/tcpdf-compat/install/ dan /integrations/tcpdf-compat/quickstart/.
- Aktifkan mode ketat dalam proses audit khusus (bukan di produksi):
$pdf->setStrictMode(true);. Kumpulkan setiapTcpdfNotImplementedException. Masing-masing menyebutkan parameter yang diabaikan secara persis dan petunjuk migrasi. - Untuk setiap lokasi yang melempar, pilih apakah akan membuang parameter yang diabaikan atau memigrasikan panggilan tersebut ke API modern melalui
$pdf->getDocument(). - Buat ulang baseline untuk pengujian apa pun yang menegaskan byte PDF yang persis; sebagai gantinya, tegaskan konten yang dirender atau properti struktural.
- Nonaktifkan mode ketat dan terapkan jalur kode yang telah diaudit. Pertahankan tugas CI berkala dengan mode ketat untuk menangkap regresi saat Anda memfaktor ulang.
Prosedur lengkap dengan kode: /integrations/tcpdf-compat/migration/.
Lihat juga
Bagian berjudul “Lihat juga”docs/TCPDF_COVERAGE.md— matriks cakupan yang otoritatif dan terverifikasi oleh pengujian (di dalam repositori)- /integrations/tcpdf-compat/migration/ — strategi migrasi TCPDF-ke-NextPDF menyeluruh
- /integrations/tcpdf-compat/configuration/ — mode ketat dan konfigurasi adaptor
- /integrations/tcpdf-compat/security-and-operations/ — postur enkripsi dan tanda tangan
- /integrations/tcpdf-compat/integration/ — menyambungkan adaptor ke dalam aplikasi
- /integrations/tcpdf-compat/boot-and-discovery/ — registrasi alias kelas dan eksposur facade