Referensi API kompatibilitas TCPDF
Sekilas
Bagian berjudul “Sekilas”Paket nextpdf/compat-legacy mengekspos satu kelas utama, NextPDF\Compat\Tcpdf\TCPDF. Kelas ini mengikuti API publik TCPDF 6.x, tetapi merender dengan mesin NextPDF modern. Paket ini juga menyertakan permukaan pendukung kecil: LegacyBootstrap untuk alias kelas global, permukaan konfigurasi AdaptationConfig/LegacyDefaults, kelas bridge internal untuk output, konstruksi, warna, satuan, dan format halaman, serta exception kompatibilitas. Gunakan paket ini sebagai alat bantu migrasi, bukan sebagai dependensi permanen. Tabel cakupan metode menjadi rujukan untuk status lengkap metode legacy. Halaman ini hanya mendokumentasikan permukaan yang sebaiknya dijadikan dependensi eksplisit oleh kode aplikasi.
Mulai dari sini: Jika Anda baru mengenal paket ini, buat instance NextPDF\Compat\Tcpdf\TCPDF, lakukan panggilan TCPDF biasa Anda (AddPage(), SetFont(), Cell()), dan akhiri dengan Output($name, $dest). Kelas ini adalah titik masuk untuk hampir semua hal di bawah ini. Untuk contoh awal yang dapat dijalankan, lihat Tugas umum.
Tugas umum
Bagian berjudul “Tugas umum”Berikut tugas paket yang paling sering Anda gunakan. Setiap blok telah diverifikasi terhadap sumber adapter dan berjalan apa adanya.
Hasilkan berkas Portable Document Format (PDF) dengan panggilan TCPDF yang sudah dikenal, lalu tangkap sebagai string untuk antrean, respons HTTP, atau penyimpanan:
<?php
declare(strict_types=1);
require __DIR__ . '/vendor/autoload.php';
use NextPDF\Compat\Tcpdf\TCPDF;
$pdf = new TCPDF('P', 'mm', 'A4');$pdf->SetTitle('Invoice 1234');$pdf->SetFont('helvetica', '', 12);$pdf->AddPage();$pdf->Cell(0, 10, 'Hello from the NextPDF engine', 1, 1, 'C');
$bytes = $pdf->Output('invoice.pdf', 'S');Apa yang dilakukannya: Membangun dokumen PDF 2.0 melalui adapter berbentuk TCPDF. Panggilan ini mengembalikan byte mentah (%PDF...) karena tujuan 'S' diteruskan melalui OutputBridge ke Document::getPdfData() alih-alih mencetaknya, sehingga aman digunakan di dalam worker atau controller.
Daftarkan alias global satu kali saat boot agar kode new \TCPDF(...) yang sudah ada dapat berjalan tanpa menyunting sumber:
<?php
declare(strict_types=1);
require __DIR__ . '/vendor/autoload.php';
use NextPDF\Compat\Tcpdf\LegacyBootstrap;
LegacyBootstrap::enableAliases();
$pdf = new \TCPDF('P', 'mm', 'A4'); // resolves to the adapter$pdf->AddPage();$pdf->Cell(0, 10, 'Legacy call site, modern engine');$pdf->Output(__DIR__ . '/legacy.pdf', 'F');Apa yang dilakukannya: enableAliases() mendaftarkan \TCPDF (dan helper \TCPDF_STATIC/\TCPDF_FONTS/\TCPDF_COLORS/\TCPDF_IMAGES) secara idempoten hanya ketika nama-nama tersebut belum didefinisikan. Kode legacy yang tidak diubah kemudian berjalan di atas adapter.
Audit migrasi dengan memunculkan setiap parameter TCPDF yang biasanya akan diabaikan adapter secara diam-diam:
<?php
declare(strict_types=1);
require __DIR__ . '/vendor/autoload.php';
use NextPDF\Compat\Tcpdf\Exception\TcpdfNotImplementedException;use NextPDF\Compat\Tcpdf\TCPDF;
$pdf = new TCPDF();$pdf->setStrictMode(true);$pdf->AddPage();$pdf->SetFont('helvetica', '', 12);
try { $pdf->Image('photo.jpg', 10, 10, 50, 0, '', '', '', true, 300);} catch (TcpdfNotImplementedException $e) { fwrite(STDERR, $e->getMessage() . "\n"); // names every ignored parameter}Apa yang dilakukannya: Dengan setStrictMode(true), panggilan yang tidak dapat mereproduksi perilaku TCPDF akan melemparkan TcpdfNotImplementedException dan menyebutkan setiap parameter yang diabaikan. Ini mengubah degradasi diam-diam menjadi daftar pekerjaan migrasi. Jalankan hanya selama proses audit; jangan pernah menjalankannya di lingkungan produksi.
Adapter utama
Bagian berjudul “Adapter utama”Tabel ini merangkum permukaan adapter kanonis. Gunakan untuk menemukan kelas yang Anda instansiasi (TCPDF), metode strict-mode dan escape-hatch-nya, serta kontrak yang diimplementasikannya.
| Simbol | Parameter | Perilaku standar | Mengembalikan | Melempar atau gagal dengan | Catatan |
|---|---|---|---|---|---|
NextPDF\Compat\Tcpdf\TCPDF | Parameter konstruktor mengikuti bentuk TCPDF legacy melalui ConstructorBridge. | Membuat adapter yang didukung oleh dokumen NextPDF. | TCPDF | Exception validasi konstruktor atau fitur yang tidak didukung. | Gunakan selama migrasi, bukan untuk kode NextPDF native baru. |
TCPDF::getDocument() | tidak ada. | Mengembalikan dokumen NextPDF yang mendasarinya. | NextPDF\Core\Document | tidak ada yang diharapkan. | Gunakan sebagai escape hatch untuk kode migrasi yang harus mencampur panggilan legacy dan native. |
TCPDF::getUnitConverter() | tidak ada. | Mengembalikan konverter yang dibuat dari satuan legacy. | UnitConverter | tidak ada yang diharapkan. | Gunakan untuk diagnostik migrasi, bukan kode aplikasi biasa. |
TCPDF::setStrictMode(bool $enabled) | Flag strict-mode. | Mengaktifkan atau menonaktifkan kegagalan eksplisit untuk perilaku kompatibilitas yang tidak didukung. | static | tidak ada yang diharapkan. | Biarkan aktif selama audit migrasi. |
TCPDF::isStrictMode() | tidak ada. | Mengembalikan flag strict-mode saat ini. | bool | tidak ada yang diharapkan. | Berguna dalam asersi pengujian. |
TCPDF metode legacy | Bervariasi menurut metode. | Metode yang didukung dipetakan ke panggilan dokumen inti; metode yang tidak didukung gagal secara eksplisit. | Bervariasi menurut metode. | TcpdfNotImplementedException atau UnsupportedFeatureException. | Periksa cakupan metode sebelum mengandalkan sebuah metode. |
CompatAdapterInterface::getDocument() | tidak ada. | Metode kontrak yang diimplementasikan oleh TCPDF. | Document | tidak ada yang diharapkan. | Memungkinkan tooling menjangkau dokumen native. |
CompatAdapterInterface::Output(string $name = '', string $dest = '') | Nama berkas dan tujuan legacy. | Mendelegasikan ke output bridge. | string | Galat penulisan inti atau tujuan yang tidak didukung. | Mencerminkan output TCPDF legacy; TCPDF::Output konkret menyediakan nilai standar 'doc.pdf'/'I'. |
Grup metode legacy
Bagian berjudul “Grup metode legacy”Tabel ini memetakan keluarga metode TCPDF yang dicakup oleh adapter. Gunakan tabel ini untuk menemukan panggilan legacy sebelum Anda memeriksa status persisnya di cakupan metode.
| Grup | Simbol representatif | Perilaku standar | Catatan |
|---|---|---|---|
| Siklus hidup dan output | Open(), Close(), Output(), getPDFData() | Mempertahankan siklus hidup dokumen bergaya TCPDF di atas dokumen native. | Utamakan API output native setelah migrasi. |
| Metadata | SetTitle(), SetAuthor(), SetSubject(), SetKeywords(), SetCreator() | Memetakan setter metadata ke dokumen yang mendasarinya. | Pertahankan normalisasi metadata di dalam kode aplikasi. |
| Halaman dan pemosisian | AddPage(), setPage(), lastPage(), GetX(), SetXY() | Mengonversi satuan dan koordinat legacy ke operasi halaman native. | Verifikasi pemosisian absolut secara visual setelah migrasi. |
| Margin dan tata letak | SetMargins(), SetAutoPageBreak(), setCellPaddings(), getMargins() | Menyimpan status kompatibilitas dan memetakan nilai yang didukung. | Perilaku jeda halaman TCPDF yang kompleks mungkin memerlukan tinjauan manual. |
| Fon dan teks | SetFont(), AddFont(), Cell(), MultiCell(), Write(), Text() | Mengarahkan operasi teks umum ke API fon dan teks native. | Periksa perilaku CJK dan encoding dengan fon produksi. |
| HTML | writeHTML(), writeHTMLCell(), fixHTMLCode() | Meneruskan HTML yang didukung ke pipeline HTML native. | Renderer native bukan klon HTML TCPDF yang lengkap. |
| Gambar dan penggambaran | Image(), Line(), Rect(), Circle(), SetDrawColor() | Memetakan operasi grafis yang didukung melalui concern adapter. | Format vektor atau format khusus yang tidak didukung gagal secara eksplisit. |
| Navigasi dan anotasi | Bookmark(), AddLink(), SetLink(), Annotation() | Mempertahankan panggilan navigasi umum jika dipetakan. | Validasi outline dan tautan yang dihasilkan. |
| Keamanan dan tanda tangan | SetProtection(), setSignature(), setTimeStamp(), setUserRights() | Menjembatani panggilan keamanan legacy yang didukung ke fitur native. | Perlakukan output kriptografis sebagai gerbang verifikasi terpisah. |
| Formulir, templat, transformasi | TextField(), startTemplate(), StartTransform(), Rotate(), Scale() | Mengimplementasikan subset yang didukung dan gagal secara lantang untuk perilaku yang tidak didukung. | Audit setiap panggilan terhadap cakupan metode sebelum peluncuran. |
Bootstrap dan konfigurasi
Bagian berjudul “Bootstrap dan konfigurasi”Gunakan tabel ini saat Anda menyambungkan adapter ke jalur boot aplikasi, mendaftarkan alias global, atau memilih antara konstanta legacy dan AdaptationConfig modern.
| Simbol | Parameter | Perilaku standar | Mengembalikan | Melempar atau gagal dengan | Catatan |
|---|---|---|---|---|---|
LegacyBootstrap::enableAliases() | tidak ada. | Mendaftarkan alias kompatibilitas satu kali. | void | Galat autoload atau lingkungan. | Gunakan hanya ketika kode legacy mengharapkan nama TCPDF ada secara global. |
LegacyBootstrap::isRegistered() | tidak ada. | Melaporkan apakah alias telah didaftarkan. | bool | tidak ada yang diharapkan. | Berguna dalam pengujian bootstrap. |
LegacyBootstrap::resetForTesting() | tidak ada. | Menghapus status pendaftaran untuk pengujian. | void | tidak ada yang diharapkan. | Helper khusus pengujian. |
AdaptationConfig | Flag adapter dan kontrol migrasi. | Menggunakan nilai standar paket jika tidak diberikan. | AdaptationConfig | Nilai opsi yang tidak valid. | Pertahankan konfigurasi tetap eksplisit selama audit migrasi. |
AdaptationConfig::fromLegacyConstants() | tidak ada. | Membaca konstanta legacy yang dikenal dan membangun objek konfigurasi. | AdaptationConfig | Nilai konstanta legacy yang tidak valid. | Helper transisional untuk aplikasi legacy berukuran besar. |
LegacyDefaults | tidak ada. | Menyediakan nilai legacy standar. | Nilai standar. | tidak ada yang diharapkan. | Tempat terpusat untuk nilai standar kompatibilitas. |
Bridge dan helper
Bagian berjudul “Bridge dan helper”Kelas konversi internal ini menggerakkan adapter. Gunakan tabel ini saat Anda berkontribusi pada cakupan adapter atau mendiagnosis bagaimana suatu argumen legacy diterjemahkan. Untuk kode aplikasi sehari-hari, utamakan permukaan adapter publik.
| Simbol | Parameter | Perilaku standar | Mengembalikan | Melempar atau gagal dengan | Catatan |
|---|---|---|---|---|---|
ConstructorBridge | Daftar argumen konstruktor legacy. | Menormalkan opsi legacy menjadi konfigurasi NextPDF. | Data konstruktor. | Nilai argumen legacy yang tidak valid. | Digunakan secara internal oleh adapter. |
CellParameterAdapter | Parameter cell TCPDF. | Memetakan argumen posisional legacy ke opsi tata letak teks inti. | Parameter yang sudah diadaptasi. | Dimensi atau perataan yang tidak valid. | Utamakan metode inti native dalam kode baru. |
OutputBridge::dispatch(Document $document, string $filename, string $dest) | Dokumen native, nama berkas, dan tujuan legacy. | Memetakan perilaku inline/download/save ke API output NextPDF. | string | Galat penulisan inti; tujuan yang tidak didukung. | Validasi nama berkas dan root penyimpanan sebelum output. |
OutputBridge::resolveDestination(string $dest) | Kode tujuan legacy. | Mengonversi tujuan menjadi tujuan output native. | OutputDestination | Galat tujuan yang tidak didukung. | Menjaga pemetaan tujuan tetap terpusat. |
ColorTranslator | Argumen warna TCPDF. | Menormalkan bentuk warna legacy. | Nilai warna inti. | Nilai warna yang tidak valid. | Digunakan oleh concern warna dan penggambaran. |
PageFormatResolver | Input format halaman legacy. | Memetakan nama yang dikenal ke ukuran halaman inti. | Nilai format halaman. | Format tidak dikenal. | Gunakan ukuran halaman native eksplisit setelah migrasi. |
UnitConverter | Nilai dan satuan pengukuran legacy. | Mengonversi ke satuan inti. | Nilai numerik. | Satuan tidak valid. | Membantu mempertahankan perilaku tata letak legacy. |
Exception
Bagian berjudul “Exception”Gunakan tabel ini saat panggilan migrasi gagal secara eksplisit. Tabel ini memisahkan kegagalan “tidak diimplementasikan” dari “dikenal tetapi tidak didukung” dan menunjukkan jalur pemulihan.
| Simbol | Makna | Pemulihan |
|---|---|---|
TcpdfNotImplementedException | Adapter sengaja tidak mengimplementasikan metode legacy yang diminta. | Ganti panggilan dengan API NextPDF native atau hapus dependensinya. |
TcpdfNotImplementedException::forSilentIgnore() | Suatu panggilan legacy yang sebelumnya akan diabaikan kini dimunculkan demi kejelasan migrasi. | Putuskan apakah perilaku no-op eksplisit dapat diterima. |
TcpdfNotImplementedException::forUnimplemented() | Suatu panggilan legacy tidak memiliki jalur adapter yang diimplementasikan. | Ganti panggilan tersebut atau isolasi di balik kode migrasi. |
UnsupportedFeatureException | Fitur legacy dikenal tetapi tidak didukung dalam batas adapter. | Periksa panduan migrasi dan isolasi fitur tersebut di balik adapter aplikasi. |
UnsupportedFeatureException::forMethod() | Membuat galat fitur-tidak-didukung yang spesifik per metode. | Gunakan dalam kontribusi kompatibilitas untuk mempertahankan pesan kegagalan yang konsisten. |
Catatan pengembangan
Bagian berjudul “Catatan pengembangan”- Perlakukan adapter sebagai alat migrasi. Kode baru sebaiknya menargetkan API NextPDF inti secara langsung.
- Perilaku yang tidak didukung sebaiknya gagal secara lantang. Jangan menangkap exception kompatibilitas lalu melanjutkan dengan dokumen parsial kecuali aplikasi secara eksplisit menerima risiko itu.
- Jaga perubahan migrasi tetap kecil dan verifikasi setiap metode legacy terhadap tabel cakupan.