Configuração

O TCPDF-Next vem com padrões sensatos que funcionam imediatamente. Toda configuração pode ser substituída no momento da criação do documento ou posteriormente via setters fluentes.

Padrões do Documento

Quando você chama Document::create(), os seguintes padrões se aplicam, a menos que você especifique o contrário:

Configuração	Padrão	Descrição
Tamanho da página	PageSize::A4	ISO A4 (210 × 297 mm)
Orientação	Orientation::Portrait	Modo retrato
Unidade	Unit::Millimeter	Todas as medidas em milímetros
Margem esquerda	15 mm	Margem esquerda da página
Margem superior	27 mm	Margem superior da página
Margem direita	15 mm	Margem direita da página
Margem inferior	25 mm	Margem inferior da página
Quebra automática	true	Quebra de página automática próxima à margem inferior
Fonte	Helvetica, 12 pt	Família e tamanho de fonte padrão

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,
);

Margens

As margens podem ser definidas globalmente ou por página:

use Yeeefang\TcpdfNext\Core\ValueObjects\Margin;

// Margens globais
$doc->setMargins(new Margin(
    left: 20,
    top: 30,
    right: 20,
    bottom: 25,
));

// Substituição para uma página específica
$doc->addPage(
    margin: new Margin(left: 10, top: 10, right: 10, bottom: 10),
);

Caminhos e Diretórios de Fontes

O TCPDF-Next procura arquivos de fontes em um conjunto configurável de diretórios. As fontes embutidas (Helvetica, Courier, Times, Symbol, ZapfDingbats) estão sempre disponíveis. Para fontes personalizadas ou Unicode, registre caminhos adicionais:

use Yeeefang\TcpdfNext\Core\Config\FontConfig;

$doc->configureFonts(function (FontConfig $config): void {
    // Adicionar um diretório contendo arquivos .ttf / .otf
    $config->addDirectory('/path/to/my/fonts');

    // Adicionar um arquivo de fonte individual com um alias de família
    $config->addFont('/path/to/MyFont-Regular.ttf', alias: 'MyFont');
});

TIP

Os arquivos de fontes são incorporados como subconjuntos por padrão, mantendo a saída PDF compacta. A incorporação completa pode ser habilitada por fonte quando necessário.

Configurações de Criptografia

A criptografia PDF é configurada através do 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,
    ],
));

Nível	Descrição
EncryptionLevel::RC4_40	RC4 legado de 40 bits (não recomendado)
EncryptionLevel::RC4_128	RC4 de 128 bits
EncryptionLevel::AES128	AES de 128 bits
EncryptionLevel::AES256	AES de 256 bits (recomendado)

Configurações de PDF com Tags

PDFs com tags (acessíveis) melhoram o suporte a leitores de tela e são exigidos pelo PDF/UA. Habilite a marcação globalmente:

$doc->enableTaggedPdf();

// Opcionalmente defina o idioma do documento para acessibilidade
$doc->setLanguage('en');

Quando o modo de PDF com tags está ativo, tags estruturais (<P>, <H1>-<H6>, <Table>, etc.) são emitidas automaticamente pelas APIs de texto e tabela.

Modo Determinístico

Por padrão, os PDFs contêm timestamps e identificadores únicos que tornam cada saída única. O modo determinístico remove esses elementos, produzindo saída byte-a-byte idêntica para a mesma entrada — útil para testes de snapshot e builds reproduzíveis:

$doc->enableDeterministicMode();

WARNING

O modo determinístico remove datas de criação/modificação e o identificador único do arquivo. Não use em documentos que necessitam desses campos de metadados.

Exemplo de Configuração Completa

Abaixo está um trecho único mostrando todas as principais opções de configuração 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,
);

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

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

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

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

// Saída determinística (para testes)
// $doc->enableDeterministicMode();

// Metadados
$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');