기본 사용법

이 페이지에서는 모든 TCPDF-Next 문서의 기본 구성 요소를 안내합니다: 문서 생성, 페이지 추가, 텍스트 작성, 이미지 임베딩, 출력 생성.

문서 생성

Document::create() 정적 팩토리는 모든 PDF의 단일 진입점입니다:

use Yeeefang\TcpdfNext\Core\Document;

$doc = Document::create();

모든 매개변수는 선택 사항입니다 — 기본값은 밀리미터 단위의 A4 세로 문서를 제공합니다. 전체 옵션 목록은 설정 페이지를 참조하세요.

페이지 추가

문서는 빈 상태로 시작합니다. 콘텐츠를 작성하기 전에 addPage()를 최소 한 번 호출하세요:

use Yeeefang\TcpdfNext\Core\Enums\PageSize;
use Yeeefang\TcpdfNext\Core\Enums\Orientation;
use Yeeefang\TcpdfNext\Core\ValueObjects\Margin;

// 문서 기본값으로 페이지 추가
$doc->addPage();

// 커스텀 여백이 있는 가로 Letter 페이지 추가
$doc->addPage(
    pageSize: PageSize::Letter,
    orientation: Orientation::Landscape,
    margin: new Margin(left: 10, top: 10, right: 10, bottom: 10),
);

사용 가능한 페이지 크기

PageSize는 모든 표준 ISO 및 북미 크기를 포함하는 Backed 열거형입니다:

열거형 값	크기
PageSize::A3	297 x 420 mm
PageSize::A4	210 x 297 mm
PageSize::A5	148 x 210 mm
PageSize::Letter	215.9 x 279.4 mm
PageSize::Legal	215.9 x 355.6 mm

커스텀 크기는 PageSize::custom(width, height)를 통해 지원됩니다.

폰트 설정

TCPDF-Next에는 표준 PDF 기본 폰트와 유니코드 지원 DejaVu Sans 패밀리가 번들되어 있습니다.

// 내장 기본 폰트
$doc->setFont('Helvetica', size: 12);

// 내장 유니코드 폰트
$doc->setFont('DejaVuSans', size: 10);

// 볼드 / 이탤릭 변형
$doc->setFont('Helvetica', style: FontStyle::Bold, size: 14);
$doc->setFont('Helvetica', style: FontStyle::BoldItalic, size: 14);

커스텀 폰트

TrueType 또는 OpenType 폰트를 등록한 후 별칭으로 사용하세요:

use Yeeefang\TcpdfNext\Core\Config\FontConfig;

$doc->configureFonts(function (FontConfig $config): void {
    $config->addFont('/fonts/Inter-Regular.ttf', alias: 'Inter');
});

$doc->setFont('Inter', size: 11);

텍스트 출력

TCPDF-Next는 페이지에 텍스트를 배치하는 네 가지 메서드를 제공합니다. 각각 다른 레이아웃 요구사항에 적합합니다.

cell()

한 줄 셀을 인쇄합니다. 레이블, 테이블 셀, 짧은 텍스트에 적합합니다:

$doc->cell(
    width: 80,
    height: 10,
    text: 'Invoice #1042',
    border: true,
    align: Align::Center,
);

multiCell()

주어진 너비 내에서 자동으로 줄 바꿈되는 텍스트를 인쇄합니다. 각 호출 후 커서가 아래로 이동합니다:

$doc->multiCell(
    width: 0,        // 0 = 사용 가능한 전체 너비
    height: 7,
    text: 'This is a longer paragraph that will wrap across multiple lines '
        . 'based on the available width and the current font size.',
);

text()

절대 (x, y) 위치에 텍스트를 배치합니다. 커서를 이동하지 않습니다:

$doc->text(x: 105, y: 20, text: 'Centered Title', align: Align::Center);

write()

현재 커서 위치에 인라인 텍스트를 작성합니다. 링크를 지원하며 단락 내에서 자연스럽게 흐릅니다:

$doc->write(height: 5, text: 'Visit the ');
$doc->write(height: 5, text: 'TCPDF-Next docs', link: 'https://tcpdf-next.dev');
$doc->write(height: 5, text: ' for more information.');

이미지

파일 경로에서

$doc->imageFromFile(
    path: '/images/logo.png',
    x: 15,
    y: 15,
    width: 40,
);

문자열 또는 리소스에서

$binary = file_get_contents('https://example.com/photo.jpg');

$doc->image(
    data: $binary,
    x: 15,
    y: 60,
    width: 50,
    type: 'JPEG',
);

지원 형식: PNG, JPEG, GIF, SVG, WebP.

저장 및 출력

TCPDF-Next는 최종 PDF를 가져오는 여러 가지 방법을 제공합니다.

디스크에 저장

$doc->save('/reports/invoice-1042.pdf');

브라우저로 전송

use Yeeefang\TcpdfNext\Core\Enums\OutputDestination;

// 인라인 표시 (Content-Disposition: inline)
$doc->output('invoice.pdf', OutputDestination::Inline);

// 강제 다운로드 (Content-Disposition: attachment)
$doc->output('invoice.pdf', OutputDestination::Download);

원시 PDF 데이터 가져오기

$pdfBytes = $doc->getPdfData();

// PSR-7 응답, 큐 작업, S3 업로드 등에 사용

OutputDestination 열거형

값	동작
OutputDestination::Inline	인라인 보기를 위해 브라우저로 전송
OutputDestination::Download	파일 다운로드로 브라우저에 전송
OutputDestination::File	파일 경로에 기록 (save()에서 내부적으로 사용)
OutputDestination::String	원시 바이너리 문자열 반환 (getPdfData()에서 내부적으로 사용)

플루언트 API

대부분의 세터는 $this를 반환하여 체이닝된 플루언트 스타일을 가능하게 합니다:

use Yeeefang\TcpdfNext\Core\Document;
use Yeeefang\TcpdfNext\Core\Enums\PageSize;
use Yeeefang\TcpdfNext\Core\Enums\Orientation;
use Yeeefang\TcpdfNext\Core\Enums\Align;
use Yeeefang\TcpdfNext\Core\Enums\FontStyle;

$pdf = Document::create()
    ->setTitle('Monthly Report')
    ->setAuthor('Acme Corp')
    ->addPage(pageSize: PageSize::A4, orientation: Orientation::Portrait)
    ->setFont('Helvetica', style: FontStyle::Bold, size: 18)
    ->cell(width: 0, height: 15, text: 'Monthly Report — February 2026', align: Align::Center)
    ->ln()
    ->setFont('Helvetica', size: 11)
    ->multiCell(width: 0, height: 6, text: 'This report summarises key metrics...')
    ->save('/reports/monthly.pdf');

전체 예제

모든 것을 종합하면:

use Yeeefang\TcpdfNext\Core\Document;
use Yeeefang\TcpdfNext\Core\Enums\Align;
use Yeeefang\TcpdfNext\Core\Enums\FontStyle;
use Yeeefang\TcpdfNext\Core\Enums\OutputDestination;

$doc = Document::create();

$doc->setTitle('Hello World');
$doc->setAuthor('TCPDF-Next');

$doc->addPage();

// 헤더
$doc->setFont('Helvetica', style: FontStyle::Bold, size: 20);
$doc->cell(width: 0, height: 15, text: 'Hello, TCPDF-Next!', align: Align::Center);
$doc->ln(20);

// 본문
$doc->setFont('DejaVuSans', size: 12);
$doc->multiCell(
    width: 0,
    height: 7,
    text: 'TCPDF-Next is a modern, type-safe PDF generation library for PHP 8.5+. '
        . 'It provides a clean API, strict static analysis, and comprehensive Unicode support.',
);

// 로고
$doc->imageFromFile(path: __DIR__ . '/logo.png', x: 15, y: 80, width: 30);

// 출력
$doc->output('hello.pdf', OutputDestination::Download);

다음 단계

• 설정 — 기본값, 암호화, 접근성을 세부 조정합니다.
• 설정 — Core, Pro, Artisan이 어떻게 조합되는지 이해합니다.
• 자주 묻는 질문 — 자주 묻는 질문에 대한 답변입니다.