Configuración

TCPDF-Next viene con valores predeterminados sensatos que funcionan desde el primer momento. Cada ajuste puede ser sobrescrito al momento de crear el documento o después mediante setters fluidos.

Valores predeterminados del documento

Cuando llamas a Document::create(), se aplican los siguientes valores predeterminados a menos que especifiques otros:

Ajuste	Predeterminado	Descripción
Tamaño de página	PageSize::A4	ISO A4 (210 × 297 mm)
Orientación	Orientation::Portrait	Modo vertical
Unidad	Unit::Millimeter	Todas las medidas en milímetros
Margen izquierdo	15 mm	Margen izquierdo de la página
Margen superior	27 mm	Margen superior de la página
Margen derecho	15 mm	Margen derecho de la página
Margen inferior	25 mm	Margen inferior de la página
Salto de página automático	true	Salto de página automático cerca del margen inferior
Fuente	Helvetica, 12 pt	Familia y tamaño de fuente predeterminados

use Yeeefang\TcpdfNext\Core\Document;
use Yeeefang\TcpdfNext\Core\Enums\PageSize;
use Yeeefang\TcpdfNext\Core\Enums\Orientation;
use Yeeefang\TcpdfNext\Core\Enums\Unit;

$doc = Document::create(
    pageSize: PageSize::Letter,
    orientation: Orientation::Landscape,
    unit: Unit::Inch,
);

Márgenes

Los márgenes pueden establecerse de forma global o por página:

use Yeeefang\TcpdfNext\Core\ValueObjects\Margin;

// Márgenes globales
$doc->setMargins(new Margin(
    left: 20,
    top: 30,
    right: 20,
    bottom: 25,
));

// Sobrescribir para una página específica
$doc->addPage(
    margin: new Margin(left: 10, top: 10, right: 10, bottom: 10),
);

Rutas y directorios de fuentes

TCPDF-Next busca archivos de fuentes en un conjunto configurable de directorios. Las fuentes integradas (Helvetica, Courier, Times, Symbol, ZapfDingbats) siempre están disponibles. Para fuentes personalizadas o Unicode, registra rutas adicionales:

use Yeeefang\TcpdfNext\Core\Config\FontConfig;

$doc->configureFonts(function (FontConfig $config): void {
    // Agregar un directorio que contenga archivos .ttf / .otf
    $config->addDirectory('/path/to/my/fonts');

    // Agregar un solo archivo de fuente con un alias de familia
    $config->addFont('/path/to/MyFont-Regular.ttf', alias: 'MyFont');
});

TIP

Los archivos de fuentes se incrustan como subconjuntos por defecto, manteniendo la salida PDF compacta. La incrustación completa puede habilitarse por fuente cuando sea necesario.

Ajustes de cifrado

El cifrado PDF se configura a través del value object EncryptionConfig:

use Yeeefang\TcpdfNext\Core\Config\EncryptionConfig;
use Yeeefang\TcpdfNext\Core\Enums\EncryptionLevel;
use Yeeefang\TcpdfNext\Core\Enums\Permission;

$doc->setEncryption(new EncryptionConfig(
    level: EncryptionLevel::AES256,
    userPassword: 'reader-pass',
    ownerPassword: 'admin-pass',
    permissions: [
        Permission::Print,
        Permission::Copy,
    ],
));

Nivel	Descripción
EncryptionLevel::RC4_40	RC4 de 40 bits heredado (no recomendado)
EncryptionLevel::RC4_128	RC4 de 128 bits
EncryptionLevel::AES128	AES de 128 bits
EncryptionLevel::AES256	AES de 256 bits (recomendado)

Ajustes de PDF etiquetado

Los PDFs etiquetados (accesibles) mejoran el soporte de lectores de pantalla y son requeridos por PDF/UA. Habilita el etiquetado globalmente:

$doc->enableTaggedPdf();

// Opcionalmente establece el idioma del documento para accesibilidad
$doc->setLanguage('en');

Cuando el modo de PDF etiquetado está activo, las etiquetas estructurales (<P>, <H1>–<H6>, <Table>, etc.) se emiten automáticamente por las APIs de texto y tablas.

Modo determinístico

Por defecto, los PDFs contienen marcas de tiempo e identificadores únicos que hacen que cada salida sea única. El modo determinístico los elimina, produciendo una salida idéntica byte a byte para la misma entrada — útil para pruebas de snapshot y compilaciones reproducibles:

$doc->enableDeterministicMode();

WARNING

El modo determinístico elimina las fechas de creación/modificación y el identificador único del archivo. No lo uses para documentos que requieran estos campos de metadatos.

Ejemplo de configuración completa

A continuación se muestra un fragmento que incluye todas las opciones principales de configuración juntas:

use Yeeefang\TcpdfNext\Core\Document;
use Yeeefang\TcpdfNext\Core\Enums\PageSize;
use Yeeefang\TcpdfNext\Core\Enums\Orientation;
use Yeeefang\TcpdfNext\Core\Enums\Unit;
use Yeeefang\TcpdfNext\Core\Enums\EncryptionLevel;
use Yeeefang\TcpdfNext\Core\Enums\Permission;
use Yeeefang\TcpdfNext\Core\Config\EncryptionConfig;
use Yeeefang\TcpdfNext\Core\Config\FontConfig;
use Yeeefang\TcpdfNext\Core\ValueObjects\Margin;

$doc = Document::create(
    pageSize: PageSize::A4,
    orientation: Orientation::Portrait,
    unit: Unit::Millimeter,
);

// Márgenes
$doc->setMargins(new Margin(
    left: 15,
    top: 27,
    right: 15,
    bottom: 25,
));

// Fuentes
$doc->configureFonts(function (FontConfig $config): void {
    $config->addDirectory('/path/to/fonts');
});

// Cifrado
$doc->setEncryption(new EncryptionConfig(
    level: EncryptionLevel::AES256,
    userPassword: '',
    ownerPassword: 'secret',
    permissions: [Permission::Print],
));

// Accesibilidad
$doc->enableTaggedPdf();
$doc->setLanguage('en');

// Salida determinística (para pruebas)
// $doc->enableDeterministicMode();

// Metadatos
$doc->setTitle('Company Report');
$doc->setAuthor('TCPDF-Next');
$doc->setSubject('Monthly Summary');
$doc->setKeywords('report, finance, 2026');

$doc->addPage();
$doc->cell(text: 'Hello, configured world!');
$doc->save('/tmp/configured.pdf');