Migrasi dari TCPDF

Panduan ini membantu Anda melakukan migrasi dari legacy TCPDF (tecnickcom/tcpdf) ke TCPDF-Next. TCPDF-Next adalah penulisan ulang total dan bukan drop-in replacement, tetapi proses migrasinya sistematis dan terdefinisi dengan jelas.

Perbedaan Utama

Fitur	TCPDF (Legacy)	TCPDF-Next
Versi PHP	5.3+	8.5+
Versi PDF	PDF 1.7	PDF 2.0
Arsitektur	Class monolitik tunggal (~27.000 baris)	17 namespace modular, 142 class
Gaya API	Prosedural, method PascalCase	Fluent builder, method camelCase
Type safety	Tidak ada type	`declare(strict_types=1)`, enum, readonly
Analisis statis	Tidak ada	PHPStan Level 10, zero error
Enkripsi	RC4, AES-128, AES-256	AES-256 saja (PDF 2.0 Revision 6)
Tanda tangan	PKCS#7 dasar	PAdES B-B hingga B-LTA
PDF/A	PDF/A-1b (parsial)	PDF/A-4 (ISO 19005-4 penuh)
Cross-reference	Tabel xref legacy	Cross-reference stream
Penanganan font	Format biner proprietary	TTF/OTF standar, subsetting otomatis
Parsing HTML	Berbasis regex (terbatas)	Engine berbasis DOM (dukungan CSS lebih baik)
Dependensi	Nol	Nol

Pemetaan API: Method Lama ke Method Baru

Perubahan paling terlihat adalah API surface. TCPDF-Next menggunakan camelCase, named parameter, value object, dan fluent builder:

Legacy TCPDF	TCPDF-Next	Catatan
`new TCPDF()`	`Document::create()`	Fluent builder, named param
`$pdf->Cell()`	`$pdf->cell()`	camelCase
`$pdf->MultiCell()`	`$pdf->multiCell()`	camelCase
`$pdf->SetFont()`	`$pdf->setFont()`	camelCase
`$pdf->SetDrawColor()`	`$pdf->setDrawColor()`	camelCase
`$pdf->Output('file.pdf', 'F')`	`$pdf->save('file.pdf')`	Method eksplisit
`$pdf->Output('file.pdf', 'I')`	`$pdf->output('file.pdf', OutputDestination::Inline)`	Berbasis enum

Pembuatan Dokumen

php

$pdf = new TCPDF('P', 'mm', 'A4', true, 'UTF-8', false); 
$pdf->SetCreator('My App'); 
$pdf->SetAuthor('John Doe'); 
$pdf->SetTitle('Invoice #12345'); 
$pdf->SetKeywords('invoice, payment, monthly'); 
$pdf->setPrintHeader(false); 
$pdf->setPrintFooter(false); 
$pdf->SetMargins(15, 15, 15); 
$pdf->SetAutoPageBreak(true, 15); 
$pdf->AddPage(); 
use YeeeFang\TcpdfNext\Document\PdfDocument; 
use YeeeFang\TcpdfNext\Document\PageFormat; 
use YeeeFang\TcpdfNext\Document\Orientation; 
use YeeeFang\TcpdfNext\Document\Margins; 
$pdf = PdfDocument::create() 
    ->setCreator('My App') 
    ->setAuthor('John Doe') 
    ->setTitle('Invoice #12345') 
    ->setKeywords(['invoice', 'payment', 'monthly']) 
    ->setPageFormat(PageFormat::A4) 
    ->setOrientation(Orientation::PORTRAIT) 
    ->setMargins(Margins::uniform(15)) 
    ->setAutoPageBreak(true, bottomMargin: 15) 
    ->build(); 
$page = $pdf->addPage();

Perubahan Konfigurasi: Konstanta ke Enum

Legacy TCPDF menggunakan konstanta integer dan magic string. TCPDF-Next menggunakan enum PHP 8.1+:

php

// TCPDF: Magic integer untuk mode enkripsi
$pdf->SetProtection(['print', 'copy'], 'user', 'owner', 3); 

// TCPDF-Next: Enum type-safe
$pdf->setEncryption() 
    ->setAlgorithm(EncryptionAlgorithm::AES256) 
    ->setPermissions(Permissions::PRINT_HIGH_QUALITY | Permissions::COPY) 
    ->setUserPassword('user') 
    ->setOwnerPassword('owner') 
    ->apply();

Penanganan Warna: Array ke Color Value Object

php

// TCPDF: Array integer biasa
$pdf->SetDrawColor(255, 0, 0); 
$pdf->SetFillColor(0, 128, 255); 

// TCPDF-Next: Color value object
use YeeeFang\TcpdfNext\Color\Color; 
$canvas->setStrokeColor(Color::rgb(255, 0, 0)); 
$canvas->setFillColor(Color::rgb(0, 128, 255)); 
$canvas->setFillColor(Color::hex('#0080FF')); 
$canvas->setFillColor(Color::cmyk(100, 50, 0, 0));

Ukuran Halaman: String ke PageSize Value Object

php

// TCPDF: Magic string
$pdf = new TCPDF('P', 'mm', 'A4'); 
$pdf->AddPage('L', 'LETTER'); 

// TCPDF-Next: Enum dan value object type-safe
use YeeeFang\TcpdfNext\Document\PageFormat; 
use YeeeFang\TcpdfNext\Document\Orientation; 
$pdf = PdfDocument::create() 
    ->setPageFormat(PageFormat::A4) 
    ->build(); 
$page = $pdf->addPage(PageFormat::LETTER, Orientation::LANDSCAPE); 
$custom = $pdf->addPage(PageFormat::custom(100, 200)); // mm

Enkripsi: RC4/AES-128 ke AES-256 Saja

TCPDF-Next menghapus semua algoritma enkripsi legacy. Jika aplikasi Anda menggunakan enkripsi RC4 atau AES-128, Anda harus upgrade ke AES-256:

php

// TCPDF: Beberapa algoritma (termasuk yang tidak aman)
$pdf->SetProtection(['print'], 'user', 'owner', 0); // RC4-40 -- TIDAK AMAN
$pdf->SetProtection(['print'], 'user', 'owner', 1); // RC4-128 -- TIDAK AMAN
$pdf->SetProtection(['print'], 'user', 'owner', 2); // AES-128
$pdf->SetProtection(['print'], 'user', 'owner', 3); // AES-256

// TCPDF-Next: AES-256 saja (satu-satunya opsi aman)
$pdf->setEncryption() 
    ->setAlgorithm(EncryptionAlgorithm::AES256) // Satu-satunya opsi
    ->setUserPassword('user') 
    ->setOwnerPassword('owner') 
    ->setPermissions(Permissions::PRINT_HIGH_QUALITY) 
    ->apply();

WARNING

PDF yang dienkripsi dengan RC4 atau AES-128 oleh legacy TCPDF harus dienkripsi ulang dengan AES-256. Enkripsi RC4 tidak memberikan keamanan yang berarti -- alat untuk memecahkannya tersedia dalam hitungan detik.

Checklist Breaking Change

Tinjau checklist ini sebelum memulai migrasi:

[ ] PHP 8.5+ diperlukan -- Upgrade runtime PHP Anda. PHP 7.x dan 8.0-8.4 tidak didukung.
[ ] Perubahan namespace -- Ganti referensi class TCPDF dengan namespace YeeeFang\TcpdfNext\....
[ ] Method camelCase -- SetFont() menjadi setFont(), MultiCell() menjadi multiCell(), dll.
[ ] Constructor diganti -- new TCPDF(...) menjadi PdfDocument::create()->...->build().
[ ] Method Output diganti -- Output('file.pdf', 'F') menjadi save('file.pdf').
[ ] Perubahan format font -- Ganti file font biner TCPDF (.php + .z) dengan file TTF/OTF asli.
[ ] Method Header/Footer -- Ganti class inheritance (extends TCPDF) dengan event callback (onPageHeader()).
[ ] Upgrade enkripsi -- RC4 dan AES-128 dihapus. Migrasi ke AES-256.
[ ] Array warna -- Ganti array biasa [255, 0, 0] dengan Color::rgb(255, 0, 0).
[ ] Ukuran halaman string -- Ganti string 'A4' dengan nilai enum PageFormat::A4.
[ ] Format keyword -- Ubah string dipisahkan koma ke array: 'a, b' menjadi ['a', 'b'].
[ ] Parameter unit dihapus -- TCPDF-Next menggunakan milimeter secara default (dapat dikonfigurasi per dokumen).
[ ] Return type -- Banyak method sekarang mengembalikan hasil ber-type alih-alih void. Gunakan return value #[\NoDiscard].

Compatibility Layer (Migrasi Bertahap)

Untuk codebase besar, TCPDF-Next menyediakan compatibility layer yang memetakan sebagian besar panggilan method legacy:

php

// Ganti import Anda -- kode yang ada tetap berjalan
use YeeeFang\TcpdfNext\Compat\TcpdfCompat as TCPDF;

Compatibility layer mencakup sekitar 80% dari public API TCPDF. Method yang tidak didukung melempar DeprecatedMethodException dengan panduan ke padanan modern.

WARNING

Compatibility layer adalah alat bantu migrasi, bukan solusi permanen. Layer ini menambah overhead dan tidak mengekspos fitur canggih TCPDF-Next (tanda tangan PAdES, PDF/A-4, cross-reference stream). Rencanakan untuk menyelesaikan migrasi ke native API.

Pemetaan API Lengkap

Untuk referensi method-by-method lengkap yang mencakup 30+ method, lihat Tabel Pemetaan API.

Bacaan Lanjutan

Tabel Pemetaan API -- Pemetaan method-by-method lengkap
Ikhtisar Keamanan -- CVE yang diperbaiki dalam migrasi
Referensi API -- Dokumentasi API TCPDF-Next lengkap
FAQ -- Pertanyaan umum migrasi

Migrasi dari TCPDF ​

Perbedaan Utama ​

Pemetaan API: Method Lama ke Method Baru ​

Pembuatan Dokumen ​

Perubahan Konfigurasi: Konstanta ke Enum ​

Penanganan Warna: Array ke Color Value Object ​

Ukuran Halaman: String ke PageSize Value Object ​

Enkripsi: RC4/AES-128 ke AES-256 Saja ​

Checklist Breaking Change ​

Compatibility Layer (Migrasi Bertahap) ​

Pemetaan API Lengkap ​

Bacaan Lanjutan ​