설정

TCPDF-Next는 별도의 설정 없이 바로 작동하는 합리적인 기본값을 제공합니다. 모든 설정은 문서 생성 시 또는 이후 플루언트 세터를 통해 재정의할 수 있습니다.

문서 기본값

Document::create()를 호출하면 별도로 지정하지 않는 한 다음 기본값이 적용됩니다:

설정	기본값	설명
페이지 크기	PageSize::A4	ISO A4 (210 x 297 mm)
방향	Orientation::Portrait	세로 모드
단위	Unit::Millimeter	모든 측정값을 밀리미터로
왼쪽 여백	15 mm	왼쪽 페이지 여백
상단 여백	27 mm	상단 페이지 여백
오른쪽 여백	15 mm	오른쪽 페이지 여백
하단 여백	25 mm	하단 페이지 여백
자동 페이지 나눔	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)는 항상 사용할 수 있습니다. 커스텀 또는 유니코드 폰트의 경우 추가 경로를 등록하세요:

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 (권장)

태그된 PDF 설정

태그된(접근 가능한) PDF는 스크린 리더 지원을 개선하며 PDF/UA에서 필수입니다. 전체적으로 태깅을 활성화하세요:

$doc->enableTaggedPdf();

// 접근성을 위해 문서 언어를 선택적으로 설정
$doc->setLanguage('en');

태그된 PDF 모드가 활성화되면 텍스트 및 테이블 API에 의해 구조적 태그(<P>, <H1>-<H6>, <Table> 등)가 자동으로 생성됩니다.

결정적 모드

기본적으로 PDF에는 타임스탬프와 고유 식별자가 포함되어 매번 출력이 고유합니다. 결정적 모드는 이를 제거하여 동일한 입력에 대해 바이트 단위로 동일한 출력을 생성합니다 — 스냅샷 테스트 및 재현 가능한 빌드에 유용합니다:

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