TCPDF là một thư viện mã nguồn mở mạnh mẽ để tạo tài liệu PDF trực tiếp từ PHP, hỗ trợ Unicode, các định dạng phông chữ đa dạng (TrueType, OpenType, CID-0), đồ họa vector, mã vạch, lớp bảo mật và nhiều tính năng nâng cao. Dưới đây là tổng hợp thực tiễn dựa trên tài liệu chính thức, kinh nghiệm triển khai và tối ưu hóa trong môi trường sản xuất.

Cài đặt và khởi tạo cơ bản

Sử dụng Composer để tích hợp vào dự án:

composer require tecnickcom/tcpdf

Khởi tạo đối tượng PDF với cấu hình chuẩn:

<?php
use TCPDF;

$pdf = new TCPDF('P', 'mm', 'A4', true, 'UTF-8', false);
$pdf->setPrintHeader(false);
$pdf->setPrintFooter(false);
$pdf->setMargins(15, 15, 15);
$pdf->setAutoPageBreak(true, 15);
$pdf->AddPage();
?>

Xử lý phông chữ Unicode

TCPDF yêu cầu phông chữ phải được nhúng hoặc có sẵn trên hệ thống đích. Với nội dung tiếng Việt, nên ưu tiên các phông hỗ trợ UTF-8 như dejavusans, stsongstdlight (cho Trung – Việt) hoặc chuyển đổi thủ công bằng addTTFFont():

// Chuyển đổi và đăng ký phông từ tệp TTF
$fontPath = '/var/fonts/Roboto-Regular.ttf';
$fontName = $pdf->addTTFFont($fontPath, 'TrueTypeUnicode', '', 32);

// Thiết lập phông cho toàn bộ tài liệu
$pdf->SetFont($fontName, '', 13, '', true); // tham số cuối: bật subsetting

Lưu ý: Nếu không cần chỉnh sửa nội dung sau khi xuất PDF, hãy tắt subsetting để giảm thời gian xử lý:

$pdf->fontSubsetting = false;

Ghi nội dung — Các phương thức chủ chốt

• Cell(): Vẽ ô đơn, phù hợp cho tiêu đề, nhãn ngắn.
• MultiCell(): In khối văn bản tự động xuống dòng, hỗ trợ căn lề và nền màu.
• writeHTML(): Render HTML cơ bản (không hỗ trợ CSS phức tạp hay Flexbox/Grid).
• writeHTMLCell(): Kết hợp giữa writeHTML() và MultiCell(), kiểm soát vị trí chính xác hơn.

Ví dụ sử dụng MultiCell với nền xanh nhạt và viền:

$pdf->SetFillColor(230, 245, 255);
$pdf->SetTextColor(30, 30, 30);
$pdf->MultiCell(100, 8, 'Điều khoản thanh toán:', 1, 'L', true, 0, '', '', true, 0, false, true, 0, 'M');

Xử lý hình ảnh

TCPDF hỗ trợ tải ảnh từ URL hoặc đường dẫn cục bộ. Đối với ảnh từ mạng, đảm bảo máy chủ có thể truy cập tới nguồn (không bị chặn bởi CORS hoặc tường lửa):

// Nhúng ảnh với tỷ lệ co dãn linh hoạt
$pdf->Image('https://example.com/logo.png', 15, 20, 45, 0, '', '', 'T', false, 300, '', false, false, 0, false, false, false);

// Hoặc dùng ảnh cục bộ với độ phân giải cao hơn
$pdf->Image('/tmp/signature_123.png', 15, 260, 60, 20, '', '', 'T', false, 300, '', false, false, 0, false, false, false);

Tối ưu hiệu năng

Khi xử lý tài liệu lớn hoặc hàng loạt PDF, áp dụng các biện pháp sau:

• Tăng giới hạn bộ nhớ và thời gian thực thi trong php.ini:
  memory_limit = 512M
max_execution_time = 300
• Vô hiệu hóa các thành phần không cần thiết:
  $pdf->setLanguageArray([]);
$pdf->setViewerPreferences(['FitWindow' => true]);
• Tránh writeHTML() nếu chỉ cần văn bản thuần — dùng Cell() hoặc MultiCell() nhanh hơn 3–5 lần.
• Chia nhỏ HTML thành các khối nhỏ hơn nếu bắt buộc dùng writeHTML().

Xuất kết quả

Các chế độ xuất phổ biến:

// I: Hiển thị trực tiếp trong trình duyệt
$pdf->Output('hop_dong.pdf', 'I');

// D: Gửi file về máy người dùng dưới dạng download
$pdf->Output('hop_dong.pdf', 'D');

// S: Trả về chuỗi nhị phân để lưu vào hệ thống tệp hoặc cơ sở dữ liệu
$pdfData = $pdf->Output('hop_dong.pdf', 'S');
file_put_contents('/storage/pdf/hop_dong_'.time().'.pdf', $pdfData);

Một số lưu ý quan trọng

• TCPDF không hỗ trợ đầy đủ HTML5/CSS3 — tránh dùng <div> lồng sâu, position: absolute, hoặc thuộc tính flex.
• Các thẻ HTML phải đúng cú pháp XML (đóng đầy đủ, ví dụ: <br />, không dùng <br>).
• Khi tích hợp với hệ thống quản lý hợp đồng, khuyến nghị sinh template từ HTML tĩnh (do frontend render), sau đó truyền vào TCPDF thay vì parse nội dung từ WYSIWYG editor.
• So sánh với các thư viện khác: dompdf chậm và kém ổn định với tiếng Việt; mpdf hỗ trợ CSS tốt hơn nhưng nặng hơn về tài nguyên.