Конфигурация

TCPDF-Next поставляется с разумными настройками по умолчанию, которые работают сразу из коробки. Каждый параметр может быть переопределён при создании документа или позднее через fluent-сеттеры.

Настройки документа по умолчанию

При вызове Document::create() применяются следующие значения по умолчанию, если вы не укажете иное:

Параметр	По умолчанию	Описание
Размер страницы	PageSize::A4	ISO A4 (210 × 297 мм)
Ориентация	Orientation::Portrait	Книжная ориентация
Единица измерения	Unit::Millimeter	Все измерения в миллиметрах
Левое поле	15 мм	Левое поле страницы
Верхнее поле	27 мм	Верхнее поле страницы
Правое поле	15 мм	Правое поле страницы
Нижнее поле	25 мм	Нижнее поле страницы
Автоматический разрыв страницы	true	Автоматический разрыв вблизи нижнего поля
Шрифт	Helvetica, 12 pt	Шрифт и размер по умолчанию

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

Поля

Поля могут быть установлены глобально или для каждой страницы:

use Yeeefang\TcpdfNext\Core\ValueObjects\Margin;

// Глобальные поля
$doc->setMargins(new Margin(
    left: 20,
    top: 30,
    right: 20,
    bottom: 25,
));

// Переопределение для конкретной страницы
$doc->addPage(
    margin: new Margin(left: 10, top: 10, right: 10, bottom: 10),
);

Пути к шрифтам и директории

TCPDF-Next ищет файлы шрифтов в настраиваемом наборе директорий. Встроенные шрифты (Helvetica, Courier, Times, Symbol, ZapfDingbats) всегда доступны. Для пользовательских или Unicode-шрифтов зарегистрируйте дополнительные пути:

use Yeeefang\TcpdfNext\Core\Config\FontConfig;

$doc->configureFonts(function (FontConfig $config): void {
    // Добавить директорию с .ttf / .otf файлами
    $config->addDirectory('/path/to/my/fonts');

    // Добавить отдельный файл шрифта с псевдонимом
    $config->addFont('/path/to/MyFont-Regular.ttf', alias: 'MyFont');
});

TIP

Файлы шрифтов по умолчанию встраиваются как подмножества, сохраняя компактность PDF. Полное встраивание может быть включено для каждого шрифта при необходимости.

Настройки шифрования

Шифрование PDF настраивается через объект значений 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,
    ],
));

Уровень	Описание
EncryptionLevel::RC4_40	Устаревший 40-битный RC4 (не рекомендуется)
EncryptionLevel::RC4_128	128-битный RC4
EncryptionLevel::AES128	128-битный AES
EncryptionLevel::AES256	256-битный AES (рекомендуется)

Настройки Tagged PDF

Теговые (доступные) PDF улучшают поддержку экранных читалок и требуются стандартом PDF/UA. Включите теги глобально:

$doc->enableTaggedPdf();

// При необходимости укажите язык документа для доступности
$doc->setLanguage('en');

Когда режим Tagged PDF активен, структурные теги (<P>, <H1>–<H6>, <Table> и т.д.) автоматически генерируются API для текста и таблиц.

Детерминированный режим

По умолчанию PDF содержат временные метки и уникальные идентификаторы, которые делают каждый вывод уникальным. Детерминированный режим удаляет их, создавая побайтово идентичный вывод для одинаковых входных данных — полезно для snapshot-тестирования и воспроизводимых сборок:

$doc->enableDeterministicMode();

WARNING

Детерминированный режим удаляет даты создания/модификации и уникальный идентификатор файла. Не используйте его для документов, которым требуются эти метаданные.

Полный пример конфигурации

Ниже представлен единый фрагмент, показывающий все основные параметры конфигурации вместе:

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

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

// Шрифты
$doc->configureFonts(function (FontConfig $config): void {
    $config->addDirectory('/path/to/fonts');
});

// Шифрование
$doc->setEncryption(new EncryptionConfig(
    level: EncryptionLevel::AES256,
    userPassword: '',
    ownerPassword: 'secret',
    permissions: [Permission::Print],
));

// Доступность
$doc->enableTaggedPdf();
$doc->setLanguage('en');

// Детерминированный вывод (для тестов)
// $doc->enableDeterministicMode();

// Метаданные
$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');