Migration từ TCPDF

Hướng dẫn này giúp bạn migration dự án hiện có từ TCPDF cũ (tecnickcom/tcpdf) sang TCPDF-Next. TCPDF-Next là bản viết lại hoàn toàn và không phải drop-in replacement, nhưng quy trình migration có hệ thống và rõ ràng.

Khác biệt chính

Tính năng	TCPDF (cũ)	TCPDF-Next
Phiên bản PHP	5.3+	8.5+
Phiên bản PDF	PDF 1.7	PDF 2.0
Kiến trúc	Class đơn khối (~27,000 dòng)	17 namespace module, 142 class
Kiểu API	Procedural, method PascalCase	Fluent builder, method camelCase
Type safety	Không có type	`declare(strict_types=1)`, enum, readonly
Phân tích tĩnh	Không	PHPStan Level 10, không lỗi
Mã hóa	RC4, AES-128, AES-256	Chỉ AES-256 (PDF 2.0 Revision 6)
Chữ ký	PKCS#7 cơ bản	PAdES B-B đến B-LTA
PDF/A	PDF/A-1b (một phần)	PDF/A-4 (đầy đủ ISO 19005-4)
Cross-reference	Bảng xref cũ	Cross-reference stream
Xử lý font	Định dạng nhị phân riêng	TTF/OTF chuẩn, tự động subset
Phân tích HTML	Dựa trên Regex (hạn chế)	Engine dựa trên DOM (hỗ trợ CSS tốt hơn)
Dependency	Không	Không

Ánh xạ API: Method cũ sang method mới

Thay đổi rõ ràng nhất là API. TCPDF-Next dùng camelCase, named parameter, value object và fluent builder:

TCPDF cũ	TCPDF-Next	Ghi chú
`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 rõ ràng
`$pdf->Output('file.pdf', 'I')`	`$pdf->output('file.pdf', OutputDestination::Inline)`	Dùng Enum

Tạo Document

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();

Thay đổi cấu hình: Constant sang Enum

TCPDF cũ dùng hằng số integer và magic string. TCPDF-Next dùng PHP 8.1+ enum:

php

// TCPDF: Magic integer cho chế độ mã hóa
$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();

Xử lý màu: Array sang Color Value Object

php

// TCPDF: Array integer thuần
$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));

Kích thước trang: String sang PageSize Value Object

php

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

// TCPDF-Next: Enum và 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

Mã hóa: RC4/AES-128 sang chỉ AES-256

TCPDF-Next loại bỏ mọi thuật toán mã hóa cũ. Nếu ứng dụng dùng RC4 hoặc AES-128, bạn phải nâng cấp lên AES-256:

php

// TCPDF: Nhiều thuật toán (bao gồm thuật toán không an toàn)
$pdf->SetProtection(['print'], 'user', 'owner', 0); // RC4-40 -- KHÔNG AN TOÀN
$pdf->SetProtection(['print'], 'user', 'owner', 1); // RC4-128 -- KHÔNG AN TOÀN
$pdf->SetProtection(['print'], 'user', 'owner', 2); // AES-128
$pdf->SetProtection(['print'], 'user', 'owner', 3); // AES-256

// TCPDF-Next: Chỉ AES-256 (tùy chọn an toàn duy nhất)
$pdf->setEncryption() 
    ->setAlgorithm(EncryptionAlgorithm::AES256) // Tùy chọn duy nhất
    ->setUserPassword('user') 
    ->setOwnerPassword('owner') 
    ->setPermissions(Permissions::PRINT_HIGH_QUALITY) 
    ->apply();

WARNING

PDF mã hóa bằng RC4 hoặc AES-128 bởi TCPDF cũ nên được mã hóa lại với AES-256. Mã hóa RC4 không cung cấp bảo mật thực sự — có công cụ để phá nó trong vài giây.

Checklist Breaking Change

Xem qua checklist này trước khi bắt đầu migration:

[ ] Yêu cầu PHP 8.5+ — Nâng cấp PHP runtime. PHP 7.x và 8.0-8.4 không được hỗ trợ.
[ ] Thay đổi namespace — Thay tham chiếu class TCPDF bằng namespace YeeeFang\TcpdfNext\....
[ ] Method camelCase — SetFont() thành setFont(), MultiCell() thành multiCell(), v.v.
[ ] Constructor thay thế — new TCPDF(...) thành PdfDocument::create()->...->build().
[ ] Output method thay thế — Output('file.pdf', 'F') thành save('file.pdf').
[ ] Thay đổi định dạng font — Thay file font nhị phân TCPDF (.php + .z) bằng file TTF/OTF gốc.
[ ] Method Header/Footer — Thay kế thừa class (extends TCPDF) bằng event callback (onPageHeader()).
[ ] Nâng cấp mã hóa — RC4 và AES-128 đã bị loại bỏ. Migration sang AES-256.
[ ] Array màu — Thay array [255, 0, 0] thuần bằng Color::rgb(255, 0, 0).
[ ] String kích thước trang — Thay string 'A4' bằng giá trị enum PageFormat::A4.
[ ] Định dạng keyword — Đổi string phân cách dấu phẩy sang array: 'a, b' thành ['a', 'b'].
[ ] Tham số unit bị loại bỏ — TCPDF-Next mặc định dùng millimet (cấu hình được cho từng document).
[ ] Kiểu trả về — Nhiều method giờ trả về kết quả có type thay vì void. Dùng giá trị trả về #[\NoDiscard].

Compatibility Layer (Migration dần dần)

Cho codebase lớn, TCPDF-Next cung cấp compatibility layer ánh xạ hầu hết lời gọi method cũ:

php

// Thay import — code hiện có tiếp tục hoạt động
use YeeeFang\TcpdfNext\Compat\TcpdfCompat as TCPDF;

Compatibility layer bao phủ khoảng 80% public API của TCPDF. Method không được hỗ trợ throw DeprecatedMethodException với hướng dẫn về tương đương hiện đại.

WARNING

Compatibility layer là công cụ hỗ trợ migration, không phải giải pháp lâu dài. Nó thêm overhead và không expose các tính năng nâng cao của TCPDF-Next (chữ ký PAdES, PDF/A-4, cross-reference stream). Hãy lên kế hoạch hoàn thành migration sang native API.

Ánh xạ API đầy đủ

Để tham chiếu method-by-method toàn diện bao gồm 30+ method, xem Bảng ánh xạ API.

Đọc thêm

Bảng ánh xạ API — Ánh xạ method-by-method đầy đủ
Tổng quan bảo mật — Các sửa lỗi CVE được giải quyết trong migration
Tham chiếu API — Tài liệu API TCPDF-Next đầy đủ
FAQ — Câu hỏi migration thường gặp

Migration từ TCPDF ​

Khác biệt chính ​

Ánh xạ API: Method cũ sang method mới ​

Tạo Document ​

Thay đổi cấu hình: Constant sang Enum ​

Xử lý màu: Array sang Color Value Object ​

Kích thước trang: String sang PageSize Value Object ​

Mã hóa: RC4/AES-128 sang chỉ AES-256 ​

Checklist Breaking Change ​

Compatibility Layer (Migration dần dần) ​

Ánh xạ API đầy đủ ​

Đọc thêm ​