So sánh & hướng dẫn triển khai

Chưa chắc bạn cần package nào? Dùng wizard tương tác bên dưới, hoặc duyệt kịch bản triển khai và ma trận quyết định để tìm setup lý tưởng.

Tìm setup hoàn hảo

1

Loại dự án

2

Phiên bản PHP

3

Framework

4

HTML sang PDF

5

Tính năng Pro

Loại dự án

Tạo setup

Trình tạo cấu hình

Chọn các package và tùy chọn để tạo file cấu hình sẵn sàng sử dụng.

Package

CoreArtisanProLaravelSymfonyCodeIgniterAdaptation

Core luôn được bao gồm

Tùy chọn Docker

Image cơ sở

Font CJKCài Noto Sans CJK để hỗ trợ tiếng Trung, Nhật, HànRoadRunnerThêm RoadRunner để phục vụ HTTP với worker cố định

Code được tạo

composer require yeeefang/tcpdf-next

Kịch bản triển khai

Các môi trường hosting khác nhau có khả năng khác nhau. Đây là setup phù hợp nhất cho mỗi loại:

🏠

Shared Hosting

Hiệu năng

Gói nên dùng

Core

Quyền PHP hạn chế, không có shell. Chỉ dùng Core với font cơ bản. Không hỗ trợ Chrome/RoadRunner.

🖥

VPS (PHP-FPM)

Hiệu năng

Gói nên dùng

Core Artisan Laravel

Toàn quyền quản lý server. Cài Chrome để dùng HTML→PDF. Phù hợp hầu hết ứng dụng.

🖥

VPS + RoadRunner

RoadRunner

Hiệu năng

Gói nên dùng

Core Artisan Laravel

Worker chạy liên tục, không còn cold start. Tốc độ xử lý tăng 3-7 lần.

⚙

Server Riêng

Hiệu năng

Gói nên dùng

Core Artisan Pro Laravel

Tài nguyên đầy đủ. Phù hợp tính năng Pro (PAdES, PDF/A-4, HSM).

⚙

Server Riêng + RoadRunner

RoadRunner

Hiệu năng

Gói nên dùng

Core Artisan Pro Laravel

Tốc độ xử lý cao nhất. 9,000+ docs/s với 4 workers.

☸

Kubernetes / Docker

RoadRunner

Hiệu năng

Gói nên dùng

Core Artisan Pro Symfony

Mở rộng theo chiều ngang. RoadRunner làm worker process. Sẵn sàng cho production.

Hiệu năng: PHP-FPM chuẩn vs RoadRunner

RoadRunner giữ ứng dụng PHP trong bộ nhớ dạng persistent worker, loại bỏ cold start và tăng throughput đáng kể.

PHP-FPM tiêu chuẩn vs RoadRunner

▲ Càng cao càng tốt

PHP-FPM RoadRunner

Tài liệu đơn giản

390 docs/s

2,605 docs/s

6.7x nhanh hơn

Hóa đơn

294 docs/s

1,960 docs/s

6.7x nhanh hơn

Báo cáo 100 trang

14 docs/s

98 docs/s

7.0x nhanh hơn

4 Workers

1,500 docs/s

9,221 docs/s

6.1x nhanh hơn

PHP 8.5.3 + OPcache + JIT · Docker 4 CPUs / 16 GB · i9-13900K · Trung vị của 20 lần chạy

Khi nào dùng RoadRunner

RoadRunner được khuyến nghị khi bạn cần throughput cao (hàng trăm PDF mỗi phút) hoặc latency thấp (thời gian phản hồi dưới millisecond). Cho ứng dụng web thông thường tạo vài PDF mỗi request, PHP-FPM chuẩn hoàn toàn đủ.

Ma trận quyết định theo use case

Bạn nên cài package nào cho use case cụ thể?

\u{2705} Nên dùng\u{26AA} Tuỳ chọn— Không áp dụng

Tình huống	Core	Artisan	Pro	Laravel	Symfony	CI4	Adaptation
Tạo hoá đơn & báo cáo	✅	⚪	⚪	⚪	⚪	⚪	—
Bán hàng online (HTML→PDF)	✅	✅	⚪	⚪	⚪	⚪	—
Tài liệu hỗ trợ tiếp cận (PDF/UA)	✅	—	✅	⚪	⚪	⚪	—
Chữ ký số (PAdES)	✅	—	✅	⚪	⚪	⚪	—
Chuyển đổi từ TCPDF cũ	✅	⚪	—	⚪	⚪	⚪	✅
API xử lý lượng lớn	✅	⚪	⚪	✅	✅	⚪	—
Lưu trữ đạt chuẩn (PDF/A-4)	✅	—	✅	⚪	⚪	⚪	—
Tài liệu nhiều mã vạch	✅	—	⚪	⚪	⚪	⚪	—

Tương thích Package

Hầu hết package hoạt động cùng nhau mượt mà, với một ngoại lệ:

Kết hợp	Tương thích	Ghi chú
Core + Bất kỳ package	Có	Core luôn bắt buộc
Artisan + Bất kỳ framework	Có	Chrome CDP hoạt động với mọi framework
Pro + Laravel/Symfony/CI	Có	Tính năng enterprise đầy đủ trong mọi framework
Pro + Adaptation	Không	Adaptation bọc API TCPDF cũ; Pro mở rộng API TCPDF-Next hiện đại. Chọn một cách tiếp cận.
Adaptation + Framework	Có	Dùng Adaptation để migration code cũ trong framework

Cân nhắc CJK & Font

14 font cơ bản tích hợp (Helvetica, Times, Courier, v.v.) chỉ hỗ trợ ký tự Latin. Nếu document cần văn bản tiếng Trung, Nhật hoặc Hàn, bạn phải:

1. Nhúng font TrueType — Dùng setFont() với font TTF hỗ trợ bộ ký tự của bạn
2. Cấu hình đường dẫn font — Thiết lập biến môi trường TCPDF_FONTS_DIR hoặc dùng configuration API
3. Cân nhắc kích thước file — Font CJK thường 5-15 MB mỗi font; dùng font subset để giảm kích thước PDF

// Ví dụ: Dùng font CJK
$pdf = Document::createStandalone()
    ->addPage()
    ->setFont('/path/to/NotoSansCJK-Regular.ttf', '', 12)
    ->cell(0, 10, '你好世界 こんにちは 안녕하세요');

Font CJK khuyến nghị

• Noto Sans CJK — Font family CJK mã nguồn mở của Google (miễn phí)
• Source Han Sans — Tương đương của Adobe (miễn phí)
• Cả hai hỗ trợ Tiếng Trung Giản thể, Trung Phồn thể, Nhật và Hàn trong một file font.

Giới hạn Shared Hosting

Trên shared hosting, bạn thường không thể:

• Cài Chrome/Chromium (không dùng được Artisan package)
• Chạy process chạy dài (không dùng được RoadRunner)
• Cài PHP extension (giới hạn ở những gì được cung cấp)

Setup khuyến nghị cho shared hosting:

composer require yeeefang/tcpdf-next

Chỉ dùng Core với parser HTML tích hợp cho nhu cầu HTML sang PDF cơ bản. Cho render HTML pixel-perfect, cân nhắc nâng cấp lên VPS.

Bước tiếp theo

• Bắt đầu — Cài đặt và tạo PDF đầu tiên
• Hướng dẫn cài đặt — Cài đặt chi tiết cho mọi package
• Benchmark — Dữ liệu so sánh hiệu năng đầy đủ
• Migration từ TCPDF — Hướng dẫn migration từng bước