Panduan cepat compat-legacy

Sekilas pandang

Halaman ini memandu Anda mulai dari paket yang sudah terpasang hingga PDF selesai, lalu ke audit mode ketat yang perlu Anda jalankan sebelum migrasi. Setiap blok kode mengikuti perilaku yang ditegaskan oleh suite pengujian paket, sehingga keluaran yang ditampilkan di sini adalah keluaran yang diperiksa oleh pengujian.

Sebelum Anda mulai

Pasang paketnya dan konfirmasi bahwa tautan ke mesin berfungsi dengan mengikuti /integrations/tcpdf-compat/install/. Anda memerlukan PHP 8.4, dan nextpdf/core ^3.0 harus sudah berhasil di-resolve.

1. Hasilkan dokumen pertama Anda

Ubah impornya dan pertahankan pemanggilan bergaya TCPDF Anda. Ini persis permukaan API yang ditegaskan oleh tests/Unit/Compat/Tcpdf/TcpdfOutputTest.php.

examples/quickstart-first.php

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF('P', 'mm', 'A4');
$pdf->SetCreator('Quickstart');
$pdf->SetTitle('First Document');
$pdf->SetFont('helvetica', '', 12);
$pdf->AddPage();
$pdf->Cell(0, 10, 'Hello from the NextPDF engine', 1, 1, 'C');

$pdf->Output(__DIR__ . '/quickstart.pdf', 'F');

echo "Wrote quickstart.pdf\n";

Jalankan:

php examples/quickstart-first.php

Berkas quickstart.pdf merupakan PDF 2.0 yang valid. Suite pengujian menegaskan bahwa keluaran string yang relevan diawali dengan %PDF untuk tujuan S, F, dan E serta untuk getPDFData().

Tujuan keluaran

Output($name, $dest) memetakan kode tujuan TCPDF melalui jembatan keluaran yang aman. Suite pengujian memverifikasi perilaku ini:

$dest	Perilaku	Mengembalikan
'S'	Mengembalikan PDF sebagai string	Bita PDF (%PDF…)
'F'	Menulis PDF ke jalur yang diberikan	string kosong
'E'	Mengembalikan body MIME base64	blok Content-Type: application/pdf
'I'	Sebaris/inline (standar)	sesuai jembatan keluaran
'D'	Unduh	sesuai jembatan keluaran

Tidak seperti TCPDF lawas, Output() tidak langsung mencetak ke buffer keluaran yang aktif. Anda dapat memanggilnya dengan aman di dalam queue worker atau handler HTTP yang mengontrol responsnya sendiri. Lihat /integrations/tcpdf-compat/production-usage/.

2. Jalankan kode TCPDF yang ada tanpa perubahan

Untuk migrasi yang sesungguhnya, mulailah dengan menjalankan kode Anda yang ada hanya dengan mengubah impor atau aliasnya. Jika basis kode Anda memanggil new \TCPDF(...) pada namespace global, aktifkan alias opt-in satu kali saat boot (dibahas di /integrations/tcpdf-compat/boot-and-discovery/):

examples/quickstart-alias.php

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\LegacyBootstrap;

LegacyBootstrap::enableAliases();

// Legacy code now resolves \TCPDF to the adapter:
$pdf = new \TCPDF('P', 'mm', 'A4');
$pdf->AddPage();
$pdf->SetFont('helvetica', '', 12);
$pdf->Cell(0, 10, 'Legacy call site, modern engine');
$pdf->Output(__DIR__ . '/aliased.pdf', 'F');

LegacyBootstrap::enableAliases() bersifat idempoten. Metode ini mendaftarkan \TCPDF, \TCPDF_STATIC, \TCPDF_FONTS, \TCPDF_COLORS, dan \TCPDF_IMAGES hanya ketika kelas-kelas tersebut belum ada. Pengujian paket tests/Unit/Compat/Tcpdf/LegacyBootstrapTest.php menegaskan bahwa alias tersebut terdaftar, bahwa pemanggilannya idempoten, dan bahwa new \TCPDF() adalah instans adaptor. Jangan aktifkan alias jika pustaka TCPDF asli dimuat dalam proses yang sama; lihat /integrations/tcpdf-compat/troubleshooting/.

3. Audit dengan mode ketat

Langkah ini membuat migrasi lebih aman. Dengan mode ketat dimatikan (standar), metode yang tidak dapat mereproduksi perilaku TCPDF akan mengalami degradasi secara diam-diam. Dengan mode ketat diaktifkan, metode tersebut melempar TcpdfNotImplementedException beserta parameter persis yang diabaikan. Jalankan ini pada tahap audit khusus, jangan pernah di produksi.

examples/quickstart-strict-audit.php

<?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 {
    // 14 of these parameters are silently ignored by the adapter.
    $pdf->Image('photo.jpg', 10, 10, 50, 0, '', '', '', true, 300);
} catch (TcpdfNotImplementedException $e) {
    // The message names every ignored parameter and a migration hint.
    fwrite(STDERR, $e->getMessage() . "\n");
}

Pengujian paket tests/Unit/Compat/Tcpdf/TcpdfStrictModeTest.php menegaskan bahwa pemanggilan persis ini melempar pengecualian dalam mode ketat dan tetap diam dalam mode standar, serta bahwa pesannya memuat nama metode dan parameter yang diabaikan. Gunakan kumpulan pengecualian tersebut sebagai daftar tugas migrasi Anda — lihat /integrations/tcpdf-compat/migration/.

4. Akses API modern saat Anda membutuhkannya

Setiap instans adaptor mengekspos dokumen mesin yang mendasarinya. Gunakan dokumen tersebut untuk memanggil metode NextPDF modern yang tidak memiliki padanan di TCPDF:

examples/quickstart-escape-hatch.php

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF();
$pdf->AddPage();
$pdf->Cell(0, 10, 'Legacy call');

// Drop to the modern engine API:
$document = $pdf->getDocument();
$document->setFont('Helvetica', 'B', 16)
    ->cell(0, 10, 'Modern fluent API', newLine: true);

getDocument() mengembalikan NextPDF\Core\Document yang dibungkus oleh adaptor. Ini jalur keluar yang disarankan: pindahkan titik pemanggilan Anda ke API modern satu per satu, sampai Anda dapat menghapus adaptornya.

Perbedaan perilaku yang harus diantisipasi segera

• MultiCell() mengembalikan 1, bukan jumlah sel yang dirender. Kode yang bercabang berdasarkan nilai kembalian dari MultiCell() perlu disesuaikan.
• Error() melempar RuntimeException alih-alih memanggil die(). Kode yang mengandalkan penghentian proses harus menangkap pengecualian tersebut.
• Bita PDF persisnya berbeda dari keluaran TCPDF. Tetapkan ulang baseline asersi pengujian tingkat bita agar memeriksa konten yang dirender sebagai gantinya.

Daftar lengkap per metode ada di /integrations/tcpdf-compat/method-coverage/.

Langkah berikutnya

• /integrations/tcpdf-compat/migration/ — strategi migrasi lengkap berkas demi berkas.
• /integrations/tcpdf-compat/configuration/ — mode ketat, nilai standar, dan objek konfigurasi modern.
• /integrations/tcpdf-compat/production-usage/ — worker, buffer keluaran, dan performa.
• /integrations/tcpdf-compat/security-and-operations/ — postur enkripsi dan penandatanganan.

Lihat juga

• tests/Unit/Compat/Tcpdf/TcpdfOutputTest.php — oracle perilaku keluaran
• tests/Unit/Compat/Tcpdf/TcpdfStrictModeTest.php — oracle mode ketat
• docs/TCPDF_COVERAGE.md — matriks cakupan otoritatif