폰트

TCPDF-Next는 자동 서브셋, CJK 렌더링, 양방향 텍스트를 지원하는 TrueType, OpenType, Type1 폰트를 지원합니다. 폰트는 Document의 addFont() 메서드를 통해 로드하거나 FontManager를 통해 직접 관리합니다.

지원되는 폰트 유형

형식	확장자	비고
TrueType	.ttf	완전한 글리프 아웃라인 지원, 가장 일반적인 형식
OpenType	.otf	CFF 및 TrueType 아웃라인 변형 모두 지원
Type1	.pfb + .afm	레거시 PostScript 폰트, 메트릭 파일 필요

코어 폰트

PDF 사양은 모든 호환 뷰어가 지원해야 하는 14개의 표준 폰트("Base 14")를 정의합니다. 이들은 임베딩이 필요 없어 파일 크기가 최소화됩니다.

패밀리	스타일
Helvetica	Regular, Bold, Italic, Bold Italic
Times	Regular, Bold, Italic, Bold Italic
Courier	Regular, Bold, Italic, Bold Italic
Symbol	Regular
ZapfDingbats	Regular

use Yeeefang\TcpdfNext\Core\Document;

$pdf = Document::create()
    ->addPage()
    ->setFont('Helvetica', '', 12)
    ->cell(0, 10, 'Helvetica — the PDF workhorse', newLine: true)
    ->setFont('Times', 'I', 12)
    ->cell(0, 10, 'Times Italic — classic serif', newLine: true)
    ->setFont('Courier', 'B', 12)
    ->cell(0, 10, 'Courier Bold — monospaced', newLine: true);

사용자 정의 폰트 로딩

addFont()

TrueType 또는 OpenType 폰트 파일을 등록하고 즉시 사용합니다.

$pdf = Document::create()
    ->addFont('NotoSansTC', '', '/path/to/NotoSansTC-Regular.ttf')
    ->addPage()
    ->setFont('NotoSansTC', '', 12)
    ->cell(0, 10, '繁體中文文字', newLine: true);

여러 스타일의 폰트 패밀리

동일한 패밀리 이름으로 각 스타일 변형을 등록합니다. TCPDF-Next는 스타일 문자열과 함께 setFont()를 호출할 때 올바른 파일을 선택합니다.

$pdf = Document::create()
    ->addFont('Roboto', '', '/fonts/Roboto-Regular.ttf')
    ->addFont('Roboto', 'B', '/fonts/Roboto-Bold.ttf')
    ->addFont('Roboto', 'I', '/fonts/Roboto-Italic.ttf')
    ->addFont('Roboto', 'BI', '/fonts/Roboto-BoldItalic.ttf')
    ->addPage()
    ->setFont('Roboto', '', 11)
    ->cell(0, 10, 'Regular weight', newLine: true)
    ->setFont('Roboto', 'B', 11)
    ->cell(0, 10, 'Bold weight', newLine: true)
    ->setFont('Roboto', 'I', 11)
    ->cell(0, 10, 'Italic style', newLine: true)
    ->setFont('Roboto', 'BI', 11)
    ->cell(0, 10, 'Bold Italic', newLine: true);

폰트 서브셋

기본적으로 TCPDF-Next는 문서에 나타나는 글리프만 임베딩합니다. FontSubsetter가 PDF 직렬화 과정에서 이를 자동으로 처리합니다.

// 폰트 서브셋은 자동으로 적용됩니다 — 사용된 글리프만 임베딩됩니다
$pdf = Document::create()
    ->addPage()
    ->setFont('DejaVuSans', '', 12)
    ->cell(0, 10, 'Only these glyphs are embedded');
// 결과: 더 작은 PDF 파일 크기

서브셋이 중요한 이유

전체 CJK 폰트는 15 MB를 초과할 수 있습니다. 문서가 소수의 문자만 사용하는 경우 서브셋을 통해 임베딩되는 폰트 데이터를 수 킬로바이트로 줄일 수 있습니다. 이는 웹 배포 및 이메일 첨부에 매우 중요합니다.

서브셋 비활성화

드문 경우(예: 사용자가 임의의 문자를 입력할 수 있는 편집 가능한 폼 필드)에는 전체 폰트가 필요할 수 있습니다. 등록 시 subsetting 매개변수에 false를 전달하십시오:

$pdf->addFont('NotoSans', '', '/fonts/NotoSans-Regular.ttf', subset: false);

CJK 지원

중국어, 일본어, 한국어 텍스트에는 대규모 글리프 세트를 가진 폰트가 필요합니다. TCPDF-Next는 CjkValidator를 통해 CJK 콘텐츠를 검증하고 PDF 출력에서 올바른 인코딩을 보장합니다.

$pdf = Document::create()
    ->addFont('NotoSansCJK', '', '/fonts/NotoSansCJKtc-Regular.otf')
    ->addPage()
    ->setFont('NotoSansCJK', '', 12)
    ->cell(0, 10, '中文：你好世界', newLine: true)
    ->cell(0, 10, '日本語：こんにちは世界', newLine: true)
    ->cell(0, 10, '한국어：안녕하세요 세계', newLine: true);

CJK 폰트는 명시적으로 비활성화하지 않는 한 항상 서브셋이 적용됩니다 — 크기 절감 효과가 상당합니다.

양방향 텍스트 (BiDi)

BiDiResolver는 아랍어와 히브리어 같은 오른쪽에서 왼쪽(RTL) 스크립트의 올바른 렌더링을 위해 유니코드 양방향 알고리즘을 구현하며, LTR/RTL 혼합 콘텐츠도 지원합니다.

$pdf = Document::create()
    ->addFont('NotoSansArabic', '', '/fonts/NotoSansArabic-Regular.ttf')
    ->addPage()
    ->setFont('NotoSansArabic', '', 14)
    ->cell(0, 10, 'مرحبا بالعالم', newLine: true)   // Arabic
    ->write(10, 'Mixed: Hello مرحبا World');          // LTR + RTL

BiDi 재배열은 텍스트에 RTL 문자가 포함되면 자동으로 적용됩니다. 수동 구성은 필요하지 않습니다.

ToUnicode CMap

TCPDF-Next는 모든 임베딩된 폰트에 대해 ToUnicode CMap을 생성합니다. 이 매핑을 통해 사용자가 복사/붙여넣기를 하거나 검색 엔진이 문서를 인덱싱할 때 PDF 뷰어가 올바른 유니코드 텍스트를 추출할 수 있습니다. 이는 직렬화 과정에서 자동으로 생성됩니다.

폰트 메트릭

FontInfo 및 FontMetrics 클래스는 상세한 타이포그래피 측정값을 노출합니다.

$pdf->setFont('Helvetica', '', 12);

// 현재 폰트에서 특정 문자열 측정
$width = $pdf->getStringWidth('Hello, World!');

// 정밀한 레이아웃을 위해 메트릭 사용
$cellWidth = $pdf->getStringWidth('Total:') + 4; // 4mm 패딩 추가
$pdf->cell($cellWidth, 8, 'Total:');

메트릭에는 어센더, 디센더, 줄 간격, 캡 높이, x-높이, 글리프별 어드밴스 너비가 포함됩니다 — 모두 폰트의 내부 테이블에서 파생됩니다.

완전한 예제

use Yeeefang\TcpdfNext\Core\Document;

$pdf = Document::create()
    // 폰트 등록
    ->addFont('Roboto', '', '/fonts/Roboto-Regular.ttf')
    ->addFont('Roboto', 'B', '/fonts/Roboto-Bold.ttf')
    ->addFont('NotoSansTC', '', '/fonts/NotoSansTC-Regular.ttf')

    ->addPage()

    // 영어 제목
    ->setFont('Roboto', 'B', 18)
    ->cell(0, 12, 'Multilingual Invoice', newLine: true)
    ->ln(3)

    // 영어 본문
    ->setFont('Roboto', '', 11)
    ->cell(0, 8, 'Customer: Acme Corporation', newLine: true)
    ->cell(0, 8, 'Date: 2026-02-16', newLine: true)
    ->ln(5)

    // 중국어 섹션
    ->setFont('NotoSansTC', '', 11)
    ->cell(0, 8, '客戶名稱：台灣科技有限公司', newLine: true)
    ->cell(0, 8, '發票日期：2026年2月16日', newLine: true)

    ->save('multilingual-invoice.pdf');