效能

TCPDF-Next 的設計目標是高吞吐量的文件產生。本頁涵蓋內建的最佳化機制與實務上的效能調校建議。

延遲子引擎初始化

Document 類別持有超過 20 個子引擎（Graphics、Typography、Barcode、Forms、Layers 等）的參考，但大多數都是延遲初始化的 — 只在首次存取時才會建立。

一份僅含文字的簡單 PDF 永遠不會實例化 SVG 解析器、條碼引擎或表單欄位管理器。這讓記憶體用量與你實際使用的功能成正比。

字型子集化

TCPDF-Next 預設僅嵌入文件中實際使用的字形。FontSubsetter 會分析所有文字內容，在嵌入前從 TrueType/OpenType 字型中剔除未使用的字形。

對於使用少量字元集的文件，字型資料可從數 MB 降至數 KB。

use Yeeefang\TcpdfNext\Core\Document;

// 字型子集化預設開啟 — 無需額外設定
$pdf = Document::create()
    ->addPage()
    ->setFont('DejaVuSans', '', 12)
    ->cell(0, 10, '僅嵌入此處使用的字形。');

FlateDecode 壓縮

所有內容串流皆使用 zlib（FlateDecode）壓縮。此功能預設啟用，需要 ext-zlib PHP 擴充。壓縮通常可將 PDF 檔案大小減少 60-80%。

串流輸出（PdfWriterChunked）

對於超大型文件，分段寫入器會在頁面資料定稿後逐步清出，而非將整份 PDF 保留在記憶體中。這對呼叫端完全透明 — 相同的 save() 與 output() 方法不受文件大小影響。

use Yeeefang\TcpdfNext\Core\Document;

// 大型文件的串流輸出
$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');
// 字型子集化與 FlateDecode 壓縮自動執行

交叉參考串流

TCPDF-Next 使用交叉參考串流（PDF 1.5+）取代傳統的 xref 表格。交叉參考串流本身也經過壓縮，能產生更小的檔案 — 尤其是物件數量眾多的文件。

線性化（快速 Web 檢視）

線性化會重新排列 PDF 物件，讓第一頁能在整份檔案下載完成前就開始顯示。對任何透過 HTTP 提供的 PDF 都建議啟用：

use Yeeefang\TcpdfNext\Core\Document;

$pdf = Document::create()
    ->setLinearization(true)
    ->addPage()
    ->cell(0, 10, '瀏覽器中漸進式渲染')
    ->save('web-optimized.pdf');

Linearizer 會插入提示串流，告知檢視器如何按需擷取各頁面。

MAX_PAGES 常數

Document::MAX_PAGES 預設值為 10,000 頁。這是一道防護機制，避免產生過程中出現無窮迴圈。若你的使用情境需要更多頁數，可透過繼承類別來覆寫此常數。

最佳實踐

跨頁面重複使用字型

設定一次字型後讓它在各頁面間沿用。除非字型確實需要變更，否則避免在每一頁都呼叫 setFont()：

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

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

使用範本（XObjects）處理重複內容

若每頁都有相同的頁首、頁尾或浮水印，可將其建立為範本並套印到各頁面上。這會將內容儲存為單一 PDF 物件並多次引用，而非逐頁重複。

維持壓縮啟用

壓縮預設開啟。除非需要檢視原始 PDF 串流以進行除錯，否則不要停用它。

大型文件使用串流輸出

對於超過數百頁的文件，串流輸出可讓記憶體用量不隨頁數增長而保持穩定。

維持字型子集化

字型子集化預設開啟。請確保在正式環境中不要停用 — 完整字型嵌入可能會增加數 MB 的檔案大小。

縮小交易範圍

交易會儲存完整的文件快照。保持交易的生命週期盡可能短，以避免記憶體用量倍增。詳見交易。

總覽

功能	預設	影響
字型子集化	開啟	更小的字型資料（KB vs MB）
FlateDecode 壓縮	開啟	串流大小減少 60-80%
交叉參考串流	開啟	更小的 xref 資料
延遲初始化	開啟	記憶體用量與功能使用成正比
串流輸出	自動	大型文件維持穩定記憶體用量
線性化	關閉	建議對 Web 傳遞的 PDF 啟用