Configuration

TCPDF-Next ships with sensible defaults that work out of the box. Every setting can be overridden at document creation time or later via fluent setters.

Document Defaults

When you call Document::create(), the following defaults apply unless you specify otherwise:

Setting	Default	Description
Page size	PageSize::A4	ISO A4 (210 × 297 mm)
Orientation	Orientation::Portrait	Portrait mode
Unit	Unit::Millimeter	All measurements in millimetres
Left margin	15 mm	Left page margin
Top margin	27 mm	Top page margin
Right margin	15 mm	Right page margin
Bottom margin	25 mm	Bottom page margin
Auto page break	true	Automatic page break near bottom margin
Font	Helvetica, 12 pt	Default font family and size

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

Margins

Margins can be set globally or per-page:

use Yeeefang\TcpdfNext\Core\ValueObjects\Margin;

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

// Override for a specific page
$doc->addPage(
    margin: new Margin(left: 10, top: 10, right: 10, bottom: 10),
);

Font Paths and Directories

TCPDF-Next looks for font files in a configurable set of directories. The built-in fonts (Helvetica, Courier, Times, Symbol, ZapfDingbats) are always available. For custom or Unicode fonts, register additional paths:

use Yeeefang\TcpdfNext\Core\Config\FontConfig;

$doc->configureFonts(function (FontConfig $config): void {
    // Add a directory containing .ttf / .otf files
    $config->addDirectory('/path/to/my/fonts');

    // Add a single font file with a family alias
    $config->addFont('/path/to/MyFont-Regular.ttf', alias: 'MyFont');
});

TIP

Font files are embedded as subsets by default, keeping PDF output compact. Full embedding can be enabled per font when needed.

Encryption Settings

PDF encryption is configured through the EncryptionConfig value object:

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

Level	Description
EncryptionLevel::RC4_40	Legacy 40-bit RC4 (not recommended)
EncryptionLevel::RC4_128	128-bit RC4
EncryptionLevel::AES128	128-bit AES
EncryptionLevel::AES256	256-bit AES (recommended)

Tagged PDF Settings

Tagged (accessible) PDFs improve screen-reader support and are required by PDF/UA. Enable tagging globally:

$doc->enableTaggedPdf();

// Optionally set the document language for accessibility
$doc->setLanguage('en');

When tagged PDF mode is active, structural tags (<P>, <H1>–<H6>, <Table>, etc.) are emitted automatically by the text and table APIs.

Deterministic Mode

By default, PDFs contain timestamps and unique identifiers that make every output unique. Deterministic mode strips these, producing byte-identical output for the same input — useful for snapshot testing and reproducible builds:

$doc->enableDeterministicMode();

WARNING

Deterministic mode removes creation/modification dates and the unique file identifier. Do not use it for documents that require these metadata fields.

Full Configuration Example

Below is a single snippet showing every major configuration option together:

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

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

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

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

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

// Deterministic output (for tests)
// $doc->enableDeterministicMode();

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