Cấu hình

TCPDF-Next được cung cấp với mặc định hợp lý, sẵn sàng sử dụng ngay. Mọi thiết lập đều có thể ghi đè khi tạo document hoặc sau đó qua fluent setter.

Mặc định Document

Khi bạn gọi Document::create(), các mặc định sau áp dụng nếu bạn không chỉ định khác:

Thiết lập	Mặc định	Mô tả
Kích thước trang	PageSize::A4	ISO A4 (210 × 297 mm)
Hướng	Orientation::Portrait	Chế độ dọc
Đơn vị	Unit::Millimeter	Mọi phép đo tính bằng milimet
Margin trái	15 mm	Margin trang trái
Margin trên	27 mm	Margin trang trên
Margin phải	15 mm	Margin trang phải
Margin dưới	25 mm	Margin trang dưới
Auto page break	true	Tự động ngắt trang gần margin dưới
Font	Helvetica, 12 pt	Họ font và kích thước mặc định

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

Margin

Margin có thể đặt toàn cục hoặc theo trang:

use Yeeefang\TcpdfNext\Core\ValueObjects\Margin;

// Margin toàn cục
$doc->setMargins(new Margin(
    left: 20,
    top: 30,
    right: 20,
    bottom: 25,
));

// Ghi đè cho trang cụ thể
$doc->addPage(
    margin: new Margin(left: 10, top: 10, right: 10, bottom: 10),
);

Đường dẫn và thư mục Font

TCPDF-Next tìm file font trong tập hợp thư mục có thể cấu hình. Các font có sẵn (Helvetica, Courier, Times, Symbol, ZapfDingbats) luôn khả dụng. Để dùng font tùy chỉnh hoặc Unicode, đăng ký thêm đường dẫn:

use Yeeefang\TcpdfNext\Core\Config\FontConfig;

$doc->configureFonts(function (FontConfig $config): void {
    // Thêm thư mục chứa file .ttf / .otf
    $config->addDirectory('/path/to/my/fonts');

    // Thêm file font đơn lẻ với alias
    $config->addFont('/path/to/MyFont-Regular.ttf', alias: 'MyFont');
});

TIP

File font được nhúng dạng subset theo mặc định, giữ cho PDF output nhỏ gọn. Có thể bật nhúng đầy đủ cho từng font khi cần.

Thiết lập mã hóa

Mã hóa PDF được cấu hình qua 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,
    ],
));

Level	Mô tả
EncryptionLevel::RC4_40	RC4 40-bit cũ (không khuyến nghị)
EncryptionLevel::RC4_128	RC4 128-bit
EncryptionLevel::AES128	AES 128-bit
EncryptionLevel::AES256	AES 256-bit (khuyến nghị)

Thiết lập Tagged PDF

Tagged PDF (PDF trợ năng) cải thiện hỗ trợ trình đọc màn hình và được yêu cầu bởi PDF/UA. Bật tagging toàn cục:

$doc->enableTaggedPdf();

// Tùy chọn đặt ngôn ngữ document cho trợ năng
$doc->setLanguage('en');

Khi chế độ tagged PDF được bật, các tag cấu trúc (<P>, <H1>–<H6>, <Table>, v.v.) được tự động sinh bởi API văn bản và bảng.

Chế độ Deterministic

Mặc định, PDF chứa timestamp và định danh duy nhất khiến mỗi output khác nhau. Chế độ deterministic loại bỏ chúng, tạo output byte-giống-hệt cho cùng input — hữu ích cho snapshot testing và reproducible build:

$doc->enableDeterministicMode();

WARNING

Chế độ deterministic loại bỏ ngày tạo/sửa đổi và file identifier duy nhất. Không dùng cho tài liệu cần các trường metadata này.

Ví dụ cấu hình đầy đủ

Dưới đây là snippet hiển thị tất cả tùy chọn cấu hình chính:

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

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

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

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

// Trợ năng
$doc->enableTaggedPdf();
$doc->setLanguage('en');

// Output deterministic (cho test)
// $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');