Desempenho

O TCPDF-Next é projetado para geração de documentos de alto throughput. Esta página cobre as otimizações embutidas e melhores práticas para obter o máximo da biblioteca.

Ciclo de Vida do Worker

graph TB
    Boot["Boot: DocumentFactory"] --> Lock["Lock Registries"]
    Lock --> Loop{"HTTP Request"}
    Loop --> Create["factory.create()"]
    Create --> Gen["Generate PDF"]
    Gen --> Dispose["Dispose Document"]
    Dispose --> Loop

Inicialização Lazy de Sub-Engines

A classe Document mantém referências a mais de 20 sub-engines (Graphics, Typography, Barcode, Forms, Layers, etc.), mas a maioria é inicializada de forma lazy — são criados apenas quando acessados pela primeira vez.

Um PDF simples apenas com texto nunca instanciará o analisador SVG, motor de códigos de barras ou gerenciador de campos de formulário. Isso mantém o uso de memória proporcional às funcionalidades que você realmente usa.

Subconjuntos de Fontes

Por padrão, o TCPDF-Next incorpora apenas os glifos realmente usados no documento. O FontSubsetter analisa todo o conteúdo de texto e remove glifos não usados das fontes TrueType/OpenType antes de incorporar.

Isso pode reduzir dados de fontes de vários megabytes para poucos kilobytes em documentos que usam um conjunto pequeno de caracteres.

use Yeeefang\TcpdfNext\Core\Document;

// Subconjuntos de fontes estão ligados por padrão — nada para habilitar
$pdf = Document::create()
    ->addPage()
    ->setFont('DejaVuSans', '', 12)
    ->cell(0, 10, 'Only these glyphs are embedded.');

Compressão FlateDecode

Todos os streams de conteúdo são comprimidos usando zlib (FlateDecode). Isso é habilitado por padrão e requer a extensão PHP ext-zlib. A compressão tipicamente reduz o tamanho do PDF em 60-80%.

Saída Streaming (PdfWriterChunked)

Para documentos muito grandes, o escritor em chunks descarrega dados de página finalizados incrementalmente em vez de manter todo o PDF na memória. Isso é transparente — os mesmos métodos save() e output() funcionam independentemente do tamanho do documento.

use Yeeefang\TcpdfNext\Core\Document;

// Saída streaming para documento grande
$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');
// Subconjuntos de fontes e compressão FlateDecode acontecem automaticamente

Streams de Referência Cruzada

O TCPDF-Next usa streams de referência cruzada (PDF 1.5+) em vez de tabelas xref tradicionais. Streams de referência cruzada são comprimidos, resultando em tamanhos de arquivo menores — especialmente para documentos com muitos objetos.

Linearização (Visualização Web Rápida)

A linearização reordena objetos PDF para que a primeira página possa ser exibida antes que o arquivo inteiro seja baixado. Habilite para qualquer PDF servido via HTTP:

use Yeeefang\TcpdfNext\Core\Document;

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

O Linearizer insere hint streams que dizem aos visualizadores como buscar páginas sob demanda.

Limite de Páginas

A constante Document::MAX_PAGES padrão é 10.000 páginas. Essa é uma proteção de segurança contra loops infinitos durante a geração. Você pode sobrescrevê-la estendendo a classe se seu caso de uso requer mais.

Melhores Práticas

Reutilize Instâncias de Fontes Entre Páginas

Defina a fonte uma vez e deixe-a persistir entre páginas. Evite chamar setFont() em cada página a menos que a fonte realmente mude:

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

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

Use Templates (XObjects) para Conteúdo Repetido

Se toda página tem o mesmo cabeçalho, rodapé ou marca d'água, crie-o uma vez como template e estampe em cada página. Isso armazena o conteúdo como um único objeto PDF referenciado múltiplas vezes, ao invés de duplicá-lo.

Habilite Compressão

A compressão está ligada por padrão. Não desabilite a menos que precise inspecionar streams PDF brutos para depuração.

Use Saída Streaming para Documentos Grandes

Para documentos com mais de algumas centenas de páginas, a saída streaming mantém o uso de memória constante independentemente da contagem de páginas.

Subconjuntos de Fontes

Subconjuntos de fontes estão ligados por padrão. Certifique-se de não desabilitá-los em produção — incorporação completa de fontes pode adicionar megabytes ao tamanho do arquivo.

Minimize o Escopo de Transações

Transações armazenam um snapshot completo do documento. Mantenha-as de curta duração para evitar dobrar o uso de memória. Veja Transações para detalhes.

Resumo

Funcionalidade	Padrão	Impacto
Subconjuntos de fontes	Ligado	Fontes menores (KB vs MB)
Compressão FlateDecode	Ligado	Streams 60-80% menores
Streams de referência cruzada	Ligado	Dados xref menores
Inicialização lazy	Ligado	Memória proporcional às funcionalidades usadas
Saída streaming	Automático	Memória constante para documentos grandes
Linearização	Desligado	Habilite para PDFs entregues via web