Boot dan discovery compat-legacy NextPDF

Gambaran umum

nextpdf/compat-legacy mengekspos NextPDF\Compat\Tcpdf\TCPDF, sebuah fasad yang kompatibel dengan TCPDF dan mendelegasikan pekerjaan ke mesin NextPDF. Ini adalah lapisan kompatibilitas, bukan klona pengganti langsung. Fasad ini langsung mendelegasikan 94 dari sekitar 120 metode TCPDF 6.x yang disurvei. Metode sisanya memiliki perbedaan perilaku yang terdokumentasi; lihat /integrations/tcpdf-compat/method-coverage/.

Tidak ada hook global saat autoload. Memuat paket ini dengan require tidak membuat kelas \TCPDF global secara default. Aktifkan alias global secara eksplisit, atau, yang lebih disarankan selama migrasi, impor kelas adaptor per berkas.

Cara fasad TCPDF diekspos

Fasad ini adalah kelas yang di-autoload secara standar mengikuti PHP Standard Recommendation 4 (PSR-4):

Item	Nilai
Kelas fasad	NextPDF\Compat\Tcpdf\TCPDF
Prefiks PSR-4	NextPDF\Compat\Tcpdf\ dipetakan ke src/Compat/Tcpdf/
Kontrak bersama	NextPDF\Compat\Contracts\CompatAdapterInterface
Jalur keluar	TCPDF::getDocument() mengembalikan NextPDF\Core\Document yang dibungkus

Kelas ini sengaja bukan final. Pengguna TCPDF lama kerap membuat subkelas dari TCPDF untuk menimpa Header() dan Footer(), dan adaptor mempertahankan titik perluasan tersebut. Secara internal, kelas ini berperan sebagai fasad. Kelas ini menyusun 25 trait concern dengan tanggung jawab tunggal dan mendelegasikan semua operasi Portable Document Format (PDF) ke sebuah instans Document yang dibuat saat fasad dibangun.

Urutan boot

Diagram

Proses konstruksi adalah satu-satunya langkah “boot”. Paket ini sendiri tidak mendaftarkan service container apa pun dan tidak menjalankan bootstrap framework. Tambahkan integrasi framework sebagai lapisan tipis; lihat /integrations/tcpdf-compat/integration/.

LegacyDefaults::register() bersifat idempoten: metode ini mendefinisikan sebuah konstanta hanya jika konstanta tersebut belum didefinisikan. Konstanta yang didefinisikan oleh aplikasi selalu menang jika Anda mendefinisikannya sebelum konstruksi pertama; lihat /integrations/tcpdf-compat/configuration/ § Urutan resolusi konfigurasi.

Alias kelas global opsional

Jika basis kode Anda memanggil new \TCPDF(...) dalam namespace global dan Anda belum dapat mengubah lokasi pemanggilan tersebut, daftarkan alias global satu kali pada saat boot aplikasi:

examples/boot-aliases.php

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use NextPDF\Compat\Tcpdf\LegacyBootstrap;

LegacyBootstrap::enableAliases();

// Global names now resolve to the adapter:
$pdf = new \TCPDF('P', 'mm', 'A4');

enableAliases() mendaftarkan \TCPDF, \TCPDF_STATIC, \TCPDF_FONTS, \TCPDF_COLORS, dan \TCPDF_IMAGES. tests/Unit/Compat/Tcpdf/LegacyBootstrapTest.php menegaskan perilaku ini:

• Metode ini bersifat idempoten: memanggilnya dua kali tidak melempar eksepsi dan hanya mendaftar sekali.
• LegacyBootstrap::isRegistered() melaporkan apakah metode ini telah dijalankan.
• Setelah pendaftaran, new \TCPDF() membuat sebuah instans adaptor.

Menghindari konflik dengan instalasi TCPDF asli

Ini adalah aturan paling penting di halaman ini.

enableAliases() mendaftarkan alias hanya jika belum ada kelas dengan nama tersebut (class_exists($alias, autoload: false)). Oleh karena itu:

• Jika tecnickcom/tcpdf terpasang dan \TCPDF miliknya dimuat lebih dulu, alias dilewati secara diam-diam, dan kode Anda tetap memakai TCPDF lama, bukan adaptor.
• Menjalankan kedua pustaka dengan alias global yang diaktifkan dalam proses yang sama tidak didukung dan menghasilkan perilaku yang ambigu.

Selama migrasi, utamakan impor eksplisit per berkas (use NextPDF\Compat\Tcpdf\TCPDF;). Impor seperti ini mudah dicari dan tidak ambigu. Hapus tecnickcom/tcpdf setelah audit strict-mode lolos; lihat /integrations/tcpdf-compat/migration/ Tahap 5. Ketika \TCPDF teresolusi ke kelas yang salah, /integrations/tcpdf-compat/troubleshooting/ menyediakan langkah diagnostiknya.

Pengikatan container

Paket ini tidak menyertakan pengikatan container framework. Jika Anda mengikat fasad ke dalam sebuah container, ikatlah sebuah factory yang mengembalikan NextPDF\Compat\Tcpdf\TCPDF baru untuk setiap dokumen. State dokumen bersifat per-instans dan tidak boleh dibagikan antardokumen yang tidak berkaitan; lihat /integrations/tcpdf-compat/production-usage/ § Konkurensi. /integrations/tcpdf-compat/integration/ menunjukkan contoh pengikatan yang lazim.

Urutan resolusi konfigurasi

Saat konstruksi, adaptor meresolusi konfigurasi dengan urutan ini: argumen konstruktor terlebih dahulu, kemudian konstanta lama mana pun yang sudah didefinisikan oleh aplikasi, lalu nilai baku TCPDF 6.2.13 dari LegacyDefaults untuk setiap konstanta yang belum didefinisikan. Untuk detail lengkap serta objek AdaptationConfig modern, lihat /integrations/tcpdf-compat/configuration/.

Diagnostik

Untuk memastikan fasad telah terangkai dan tautan ke mesin teresolusi, buat sebuah adaptor, hasilkan PDF satu halaman, dan periksa prefiks %PDF. Uji keluaran paket ini menegaskan permukaan yang sama. Pemeriksaan yang dapat dijalankan tersedia di /integrations/tcpdf-compat/install/ § Verifikasi instalasi.

Untuk mendeteksi konflik dengan TCPDF asli sebelum mengaktifkan alias, periksa apakah sebuah \TCPDF global sudah ada di tempat Anda akan memanggil enableAliases(). Jika ada, alias akan dilewati. Selesaikan konflik dengan impor eksplisit, atau hapus TCPDF asli sebelum Anda mengandalkan adaptor.

Cakupan API TCPDF

Matriks cakupan yang otoritatif dan terverifikasi oleh pengujian adalah berkas dalam repo docs/TCPDF_COVERAGE.md. Ringkasan untuk pembaca, termasuk daftar metode yang diabaikan secara diam-diam dan yang belum diimplementasikan, ada di /integrations/tcpdf-compat/method-coverage/. Paket ini tidak mengklaim diri sebagai “pengganti langsung” atau “kompatibel (bukan identik per byte) dengan TCPDF”; ini adalah alternatif yang kompatibel dengan TCPDF, dengan permukaan kompatibilitas yang diketahui dan teruji serta perbedaan perilaku yang terdokumentasi.

Lihat juga

• docs/TCPDF_COVERAGE.md — sumber cakupan otoritatif (dalam repo)
• /integrations/tcpdf-compat/integration/ — merangkai fasad ke dalam sebuah aplikasi/framework
• /integrations/tcpdf-compat/method-coverage/ — perilaku dan celah per metode
• /integrations/tcpdf-compat/migration/ — strategi migrasi bertahap
• /integrations/tcpdf-compat/troubleshooting/ — diagnostik konflik alias/real-TCPDF
• tests/Unit/Compat/Tcpdf/LegacyBootstrapTest.php — oracle perilaku alias