Rendimiento

TCPDF-Next está diseñado para generación de documentos de alto rendimiento. Esta página cubre las optimizaciones integradas y las mejores prácticas para obtener el máximo de la biblioteca.

Ciclo de vida del 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

Inicialización perezosa de sub-motores

La clase Document mantiene referencias a más de 20 sub-motores (Graphics, Typography, Barcode, Forms, Layers, etc.), pero la mayoría se inicializan de forma perezosa — solo se crean cuando se acceden por primera vez.

Un PDF simple de solo texto nunca instanciará el analizador SVG, el motor de códigos de barras ni el gestor de campos de formulario. Esto mantiene el uso de memoria proporcional a las funciones que realmente usas.

Subconjuntos de fuentes

Por defecto, TCPDF-Next incrusta solo los glifos realmente usados en el documento. El FontSubsetter analiza todo el contenido de texto y elimina los glifos no usados de las fuentes TrueType/OpenType antes de incrustarlas.

Esto puede reducir los datos de fuente de varios megabytes a unos pocos kilobytes para documentos que usan un conjunto de caracteres pequeño.

use Yeeefang\TcpdfNext\Core\Document;

// Los subconjuntos de fuentes están activados por defecto — nada que habilitar
$pdf = Document::create()
    ->addPage()
    ->setFont('DejaVuSans', '', 12)
    ->cell(0, 10, 'Only these glyphs are embedded.');

Compresión FlateDecode

Todos los streams de contenido se comprimen usando zlib (FlateDecode). Esto está habilitado por defecto y requiere la extensión PHP ext-zlib. La compresión típicamente reduce el tamaño del archivo PDF en un 60-80%.

Salida en streaming (PdfWriterChunked)

Para documentos muy grandes, el escritor por bloques libera los datos de página finalizados de forma incremental en lugar de mantener todo el PDF en memoria. Esto es transparente — los mismos métodos save() y output() funcionan independientemente del tamaño del documento.

use Yeeefang\TcpdfNext\Core\Document;

// Salida en streaming para un 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');
// Los subconjuntos de fuentes y la compresión FlateDecode ocurren automáticamente

Streams de referencia cruzada

TCPDF-Next usa streams de referencia cruzada (PDF 1.5+) en lugar de tablas xref tradicionales. Los streams de referencia cruzada están a su vez comprimidos, resultando en tamaños de archivo más pequeños — especialmente para documentos con muchos objetos.

Linearización (Vista web rápida)

La linearización reordena los objetos PDF para que la primera página pueda mostrarse antes de que se descargue el archivo completo. Habilítala para cualquier PDF servido por HTTP:

use Yeeefang\TcpdfNext\Core\Document;

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

El Linearizer inserta streams de sugerencias que indican a los visores cómo obtener páginas bajo demanda.

Límite de páginas

La constante Document::MAX_PAGES tiene un valor predeterminado de 10,000 páginas. Es una protección contra bucles infinitos durante la generación. Puedes sobrescribirla extendiendo la clase si tu caso de uso requiere más.

Mejores prácticas

Reutilizar instancias de fuente entre páginas

Establece la fuente una vez y deja que se mantenga entre páginas. Evita llamar a setFont() en cada página a menos que la fuente realmente cambie:

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

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

Usar plantillas (XObjects) para contenido repetido

Si cada página tiene el mismo encabezado, pie de página o marca de agua, créalo una vez como plantilla y estámpalo en cada página. Esto almacena el contenido como un solo objeto PDF referenciado múltiples veces, en lugar de duplicarlo.

Habilitar compresión

La compresión está activada por defecto. No la deshabilites a menos que necesites inspeccionar streams PDF sin procesar para depuración.

Usar salida en streaming para documentos grandes

Para documentos que excedan unos pocos cientos de páginas, la salida en streaming mantiene el uso de memoria constante independientemente del conteo de páginas.

Subconjuntos de fuentes

Los subconjuntos de fuentes están activados por defecto. Asegúrate de no deshabilitarlos en producción — la incrustación completa de fuentes puede agregar megabytes al tamaño del archivo.

Minimizar el alcance de las transacciones

Las transacciones almacenan un snapshot completo del documento. Mantenlas de corta duración para evitar duplicar el uso de memoria. Consulta Transacciones para más detalles.

Resumen

Función	Predeterminado	Impacto
Subconjuntos de fuentes	Activado	Fuentes más pequeñas (KB vs MB)
Compresión FlateDecode	Activado	Streams 60-80% más pequeños
Streams de referencia cruzada	Activado	Datos xref más pequeños
Inicialización perezosa	Activado	Memoria proporcional a las funciones usadas
Salida en streaming	Automático	Memoria constante para documentos grandes
Linearización	Desactivado	Habilitar para PDFs entregados por web