Pemecahan masalah compat-legacy

Sekilas

Sebagian besar masalah migrasi muncul dalam beberapa pola yang berulang. Setiap entri di bawah ini mencantumkan gejala, penyebab, dan perbaikannya. Jika Anda ragu tentang metode tertentu, periksa /integrations/tcpdf-compat/method-coverage/ dan matriks otoritatif dalam repo docs/TCPDF_COVERAGE.md.

Sebelumnya proses berhenti saat terjadi galat PDF; kini eksepsi tidak tertangani

Gejala. Kode yang sebelumnya berhenti saat rendering bermasalah kini melempar RuntimeException yang tidak tertangkap, dan permintaan atau pekerjaan melaporkan galat.

Penyebab. Pemanggilan Error() warisan TCPDF memanggil die(). Sebagai gantinya, adapter secara sengaja melempar RuntimeException agar kegagalan dapat diamati.

Perbaikan. Bungkus titik masuk rendering dengan try/catch, lalu petakan eksepsinya ke kontrak galat Anda. Jangan mengembalikan perilaku die(). Lihat /integrations/tcpdf-compat/production-usage/ § Penanganan kegagalan.

`new \TCPDF()` masih mengarah ke pustaka TCPDF asli

Gejala. Anda mengaktifkan LegacyBootstrap::enableAliases(), tetapi keluarannya masih tampak seperti TCPDF warisan, atau perilakunya tidak berubah.

Penyebab. enableAliases() mendaftarkan alias hanya jika belum ada kelas dengan nama tersebut. Jika tecnickcom/tcpdf tetap dapat di-autoload dan kelas \TCPDF-nya dimuat lebih dulu, alias tersebut dilewati, dan kode Anda tetap menggunakan TCPDF warisan.

Perbaikan. Selama migrasi, gunakan impor eksplisit per berkas (use NextPDF\Compat\Tcpdf\TCPDF;) agar setiap titik pemanggilan jelas. Hapus tecnickcom/tcpdf setelah audit lolos (lihat /integrations/tcpdf-compat/migration/ Tahap 5). Jangan menjalankan kedua pustaka dengan alias global yang aktif dalam proses yang sama.

Sebuah metode “berfungsi”, tetapi parameter yang saya berikan diabaikan

Gejala. Sebuah pemanggilan berhasil dan menghasilkan berkas Portable Document Format (PDF), tetapi opsi yang Anda berikan (tautan gambar, perataan, dots per inch (DPI), warna penanda, …) tidak berpengaruh.

Penyebab. Metode tersebut termasuk dalam kumpulan yang diabaikan secara diam-diam. Metode itu menerima parameter demi kompatibilitas sumber, lalu membuangnya. Ini adalah perilaku yang terdokumentasi, bukan bug; lihat /integrations/tcpdf-compat/method-coverage/ §2.

Perbaikan. Jalankan audit dalam mode ketat untuk menemukan setiap pemanggilan semacam itu:

<?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('logo.png', 10, 10, 50, 0, '', 'https://example.com');
} catch (TcpdfNotImplementedException $e) {
    // Message lists every ignored parameter and a migration hint.
    echo $e->getMessage(), "\n";
}

Kemudian hilangkan parameter tersebut, atau nyatakan ulang melalui API modern ($pdf->getDocument()), seperti yang ditunjukkan dalam /integrations/tcpdf-compat/migration/ Tahap 4.

Nilai kembalian `MultiCell()` selalu 1

Gejala. Kode yang bercabang berdasarkan nilai kembalian MultiCell() (misalnya, untuk menghitung tinggi terpakai atau jumlah baris) berperilaku tidak tepat.

Penyebab. MultiCell() pada adapter mengembalikan penanda kompatibilitas 1, bukan jumlah sel atau jumlah baris yang dirender. Write() serupa mengembalikan 0.

Perbaikan. Jangan bercabang berdasarkan nilai kembalian ini. Jika Anda memerlukan tinggi yang dirender, hitung menggunakan getStringHeight() / getNumLines(), atau pindahkan logika itu ke API modern.

`setPDFVersion('1.4')` tidak menghasilkan berkas PDF 1.4

Gejala. Anda meminta versi PDF yang lebih lama; keluarannya tetap PDF 2.0.

Penyebab. Adapter selalu menghasilkan PDF 2.0 (ISO 32000-2). setPDFVersion() termasuk dalam kumpulan yang tidak berlaku; adapter memunculkan notice dan melanjutkan.

Perbaikan. Hapus pemanggilan tersebut. Jika konsumen di hilir membutuhkan versi PDF yang lebih lama, penuhi persyaratan itu secara terpisah; adapter tidak dapat menurunkan target versi.

`setSignature()` tidak melakukan apa pun — PDF tidak ditandatangani

Gejala. Anda memanggil setSignature() dengan sertifikat; PDF keluaran tidak memiliki tanda tangan.

Penyebab. Mesin inti tidak mengimplementasikan setSignature() melalui adapter ini. Dalam mode standar, ini berupa no-op; dalam mode ketat, ini melempar eksepsi.

Perbaikan. Penandatanganan memerlukan edisi NextPDF komersial dan API tanda tangan modern. Lihat /integrations/tcpdf-compat/security-and-operations/ § Tanda tangan digital. Jangan berharap pemanggilan setSignature() warisan menandatangani apa pun.

`Output()` merusak respons HTTP atau keluaran worker saya

Gejala. Bita PDF muncul dalam respons Hypertext Transfer Protocol (HTTP), atau log worker ikut berisi bita PDF.

Penyebab. Anda menggunakan tujuan keluaran yang menulis ke jalur keluaran (I/D) sementara Anda sendiri yang mengendalikan responsnya. Adapter tidak melakukan echo ke buffer Anda sebagaimana TCPDF warisan, tetapi I/D tetap menggerakkan keluaran mesin.

Perbaikan. Pada worker dan handler yang Anda kendalikan, gunakan Output($path, 'F') untuk menulis berkas, atau Output($name, 'S') untuk memperoleh bita dan mengirimkannya sendiri. tests/Unit/Compat/Tcpdf/Bridge/OutputBridgeTest.php menyatakan bahwa pemetaan tujuan tidak peka huruf besar-kecil dan spasi kosongnya dipangkas:

Kode	Mengembalikan	Efek samping
`S`	Bita PDF (`%PDF…`)	tidak ada
`F`	string kosong	menulis berkas
`E`	badan MIME base64	tidak ada
`FI` / `FD`	string kosong	menulis berkas, lalu keluaran mesin
`I` / `D` / tidak dikenal	string kosong	keluaran mesin (inline/unduhan)

Asersi bita-eksak PDF gagal setelah beralih

Gejala. Pengujian snapshot yang membandingkan bita PDF mentah gagal di mana-mana.

Penyebab. Mesin menggunakan implementasi PDF 2.0 yang independen. Metode yang didelegasikan menghasilkan keluaran visual yang kompatibel, tetapi bitanya berbeda. Ini wajar.

Perbaikan. Buat ulang baseline pengujian Anda agar mengasersi pada konten yang dirender (teks yang diekstrak), struktur (jumlah halaman, ukuran halaman), atau pemeriksaan ringan (str_starts_with($bytes, '%PDF')). Lihat /integrations/tcpdf-compat/migration/ Tahap 4.

Konstanta warisan `K_` / `PDF_` bernilai keliru

Gejala. Jalur kustom atau nilai standar yang Anda tetapkan melalui konstanta tidak berlaku.

Penyebab. Adapter mendefinisikan konstanta secara otomatis hanya jika belum terdefinisi, dan proses itu terjadi selama konstruksi pertama. Jika define() Anda dijalankan setelah adapter pertama dikonstruksi, nilai standar adapter sudah berlaku.

Perbaikan. Definisikan setiap konstanta kustom K_* / PDF_* di bootstrap Anda, sebelum instans adapter mana pun dibuat. Lihat /integrations/tcpdf-compat/configuration/ § Urutan resolusi konfigurasi.

Ketidakcocokan versi mesin saat konstruksi

Gejala. Konstruksi gagal atau perilaku berubah secara tidak terduga setelah pemutakhiran dependensi.

Penyebab. Adapter membutuhkan nextpdf/core ^3.0. Versi inti yang terselesaikan di luar rentang itu tidak didukung.

Perbaikan. Jalankan composer show nextpdf/core, lalu kunci mesin pada ^3.0. Lihat /integrations/tcpdf-compat/install/ § Verifikasi versi mesin.

Rujukan diagnostik singkat

Pertanyaan	Di mana mencarinya
Apa sebenarnya yang dilakukan metode X di sini?	/integrations/tcpdf-compat/method-coverage/, `docs/TCPDF_COVERAGE.md`
Pemanggilan mana saja yang kehilangan parameter?	Audit mode ketat (halaman ini; /integrations/tcpdf-compat/migration/)
Mengapa proses tidak berhenti saat terjadi galat?	/integrations/tcpdf-compat/security-and-operations/ § Perilaku yang diperkuat
Mengapa keluaran tidak ditandatangani / bukan PDF/A?	/integrations/tcpdf-compat/security-and-operations/
Konflik alias vs impor eksplisit	Halaman ini; /integrations/tcpdf-compat/boot-and-discovery/

Lihat juga

/integrations/tcpdf-compat/migration/ — migrasi bertahap yang mencegah sebagian besar masalah di atas
/integrations/tcpdf-compat/method-coverage/ — rujukan perilaku per metode
/integrations/tcpdf-compat/boot-and-discovery/ — pendaftaran alias dan penghindaran konflik
docs/TCPDF_COVERAGE.md — matriks cakupan otoritatif