Hiệu suất

TCPDF-Next được thiết kế cho tạo document throughput cao. Trang này mô tả các tối ưu tích hợp sẵn và thực hành tốt nhất để khai thác tối đa thư viện.

Vòng đời Worker

graph TB
    Boot["Boot: DocumentFactory"] --> Lock["Lock Registry"]
    Lock --> Loop{"HTTP Request"}
    Loop --> Create["factory.create()"]
    Create --> Gen["Tạo PDF"]
    Gen --> Dispose["Hủy Document"]
    Dispose --> Loop

Khởi tạo Lazy Sub-Engine

Class Document giữ tham chiếu đến hơn 20 sub-engine (Graphics, Typography, Barcode, Forms, Layers, v.v.), nhưng hầu hết được khởi tạo lazy — chúng chỉ được tạo khi truy cập lần đầu.

PDF chỉ text đơn giản sẽ không bao giờ tạo SVG parser, barcode engine hay form field manager. Điều này giữ bộ nhớ tỷ lệ thuận với tính năng bạn thực sự dùng.

Font Subsetting

Mặc định, TCPDF-Next chỉ nhúng glyph thực sự được dùng trong document. FontSubsetter phân tích mọi nội dung text và loại bỏ glyph không dùng từ font TrueType/OpenType trước khi nhúng.

Điều này có thể giảm dữ liệu font từ vài megabyte xuống vài kilobyte cho document dùng ít ký tự.

use Yeeefang\TcpdfNext\Core\Document;

// Font subsetting bật mặc định — không cần bật
$pdf = Document::create()
    ->addPage()
    ->setFont('DejaVuSans', '', 12)
    ->cell(0, 10, 'Only these glyphs are embedded.');

Nén FlateDecode

Mọi content stream được nén bằng zlib (FlateDecode). Tính năng này bật mặc định và yêu cầu PHP extension ext-zlib. Nén thường giảm kích thước file PDF từ 60-80%.

Streaming Output (PdfWriterChunked)

Cho document rất lớn, chunked writer flush dữ liệu trang đã hoàn thiện từng phần thay vì giữ toàn bộ PDF trong bộ nhớ. Điều này trong suốt — cùng method save() và output() hoạt động bất kể kích thước document.

use Yeeefang\TcpdfNext\Core\Document;

// Streaming output cho document lớn
$pdf = Document::create();
$pdf->addPage()->setFont('Helvetica', '', 10);

for ($i = 0; $i < 5000; $i++) {
    $pdf->cell(0, 5, "Row {$i}: data content here", newLine: true);
}

$pdf->save('large-document.pdf');
// Font subsetting và nén FlateDecode xảy ra tự động

Cross-Reference Stream

TCPDF-Next dùng cross-reference stream (PDF 1.5+) thay vì bảng xref truyền thống. Cross-reference stream chính chúng cũng được nén, tạo kích thước file nhỏ hơn — đặc biệt cho document có nhiều object.

Linearization (Fast Web View)

Linearization sắp xếp lại object PDF để trang đầu tiên có thể hiển thị trước khi toàn bộ file được tải. Bật cho bất kỳ PDF phục vụ qua HTTP:

use Yeeefang\TcpdfNext\Core\Document;

$pdf = Document::create()
    ->setLinearization(true)
    ->addPage()
    ->cell(0, 10, 'Progressive rendering in the browser')
    ->save('web-optimized.pdf');

Linearizer chèn hint stream cho trình xem biết cách tải trang theo yêu cầu.

Giới hạn trang

Hằng Document::MAX_PAGES mặc định là 10,000 trang. Đây là cơ chế bảo vệ chống vòng lặp vô hạn trong quá trình tạo. Bạn có thể ghi đè bằng cách extend class nếu trường hợp sử dụng yêu cầu nhiều hơn.

Thực hành tốt nhất

Tái sử dụng instance Font giữa các trang

Đặt font một lần và để nó tồn tại qua các trang. Tránh gọi setFont() mỗi trang trừ khi font thực sự thay đổi:

$pdf = Document::create()
    ->setFont('Helvetica', '', 10);

for ($i = 0; $i < 100; $i++) {
    $pdf->addPage()
        ->cell(0, 5, "Page {$i} content");
}

Dùng Template (XObject) cho nội dung lặp lại

Nếu mỗi trang có cùng header, footer hoặc watermark, tạo nó một lần dạng template rồi đóng dấu lên mỗi trang. Điều này lưu nội dung dạng một PDF object duy nhất được tham chiếu nhiều lần, thay vì trùng lặp.

Bật nén

Nén bật mặc định. Không tắt nó trừ khi bạn cần kiểm tra raw PDF stream để debug.

Dùng Streaming Output cho document lớn

Cho document vượt quá vài trăm trang, streaming output giữ bộ nhớ ổn định bất kể số lượng trang.

Subset Font

Font subsetting bật mặc định. Đảm bảo không tắt nó trong production — nhúng toàn bộ font có thể thêm nhiều megabyte vào kích thước file.

Thu nhỏ phạm vi Transaction

Transaction lưu snapshot đầy đủ document. Giữ chúng tồn tại ngắn để tránh gấp đôi bộ nhớ. Xem Transaction để biết chi tiết.

Tổng kết

Tính năng	Mặc định	Tác động
Font subsetting	Bật	Font nhỏ hơn (KB thay vì MB)
Nén FlateDecode	Bật	Stream nhỏ hơn 60-80%
Cross-reference stream	Bật	Dữ liệu xref nhỏ hơn
Khởi tạo lazy	Bật	Bộ nhớ tỷ lệ với tính năng dùng
Streaming output	Tự động	Bộ nhớ ổn định cho document lớn
Linearization	Tắt	Bật cho PDF phân phối qua web