Performance

TCPDF-Next is designed for high-throughput document generation. This page covers the built-in optimizations and best practices for getting the most out of the library.

Lazy Sub-Engine Initialization

The Document class holds references to over 20 sub-engines (Graphics, Typography, Barcode, Forms, Layers, etc.), but most are lazily initialized — they are only created when first accessed.

A simple text-only PDF will never instantiate the SVG parser, barcode engine, or form field manager. This keeps memory usage proportional to the features you actually use.

Font Subsetting

By default, TCPDF-Next embeds only the glyphs actually used in the document. The FontSubsetter analyzes all text content and strips unused glyphs from TrueType/OpenType fonts before embedding.

This can reduce font data from several megabytes to a few kilobytes for documents that use a small character set.

use Yeeefang\TcpdfNext\Core\Document;

// Font subsetting is on by default — nothing to enable
$pdf = Document::create()
    ->addPage()
    ->setFont('DejaVuSans', '', 12)
    ->cell(0, 10, 'Only these glyphs are embedded.');

FlateDecode Compression

All content streams are compressed using zlib (FlateDecode). This is enabled by default and requires the ext-zlib PHP extension. Compression typically reduces PDF file size by 60-80%.

Streaming Output (PdfWriterChunked)

For very large documents, the chunked writer flushes finalized page data incrementally instead of holding the entire PDF in memory. This is transparent — the same save() and output() methods work regardless of document size.

use Yeeefang\TcpdfNext\Core\Document;

// Streaming output for a large 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');
// Font subsetting and FlateDecode compression happen automatically

Cross-Reference Streams

TCPDF-Next uses cross-reference streams (PDF 1.5+) instead of traditional xref tables. Cross-reference streams are themselves compressed, resulting in smaller file sizes — especially for documents with many objects.

Linearization (Fast Web View)

Linearization reorders PDF objects so the first page can be displayed before the entire file is downloaded. Enable it for any PDF served over HTTP:

use Yeeefang\TcpdfNext\Core\Document;

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

The Linearizer inserts hint streams that tell viewers how to fetch pages on demand.

Page Limit

The Document::MAX_PAGES constant defaults to 10,000 pages. This is a safety guard against infinite loops during generation. You can override it by extending the class if your use case requires more.

Best Practices

Reuse Font Instances Across Pages

Set the font once and let it carry across pages. Avoid calling setFont() on every page unless the font actually changes:

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

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

Use Templates (XObjects) for Repeated Content

If every page has the same header, footer, or watermark, create it once as a template and stamp it on each page. This stores the content as a single PDF object referenced multiple times, rather than duplicating it.

Enable Compression

Compression is on by default. Do not disable it unless you need to inspect raw PDF streams for debugging.

Use Streaming Output for Large Documents

For documents exceeding a few hundred pages, streaming output keeps memory usage constant regardless of page count.

Subset Fonts

Font subsetting is on by default. Ensure you do not disable it in production — full font embedding can add megabytes to file size.

Minimize Transaction Scope

Transactions store a full document snapshot. Keep them short-lived to avoid doubling memory usage. See Transactions for details.

Summary

Feature	Default	Impact
Font subsetting	On	Smaller fonts (KB vs MB)
FlateDecode compression	On	60-80% smaller streams
Cross-reference streams	On	Smaller xref data
Lazy initialization	On	Memory proportional to features used
Streaming output	Automatic	Constant memory for large documents
Linearization	Off	Enable for web-delivered PDFs