Document API
Document 클래스(TcpdfNext\Core\Document)는 PDF 문서 생성을 위한 기본 진입점입니다. 12개의 trait로 구성되며, 각각 관련 메서드 그룹을 제공합니다. 모든 변경 메서드는 플루언트 체이닝을 위해 static을 반환합니다.
php
use TcpdfNext\Core\Document;
$pdf = Document::create()
->setTitle('Invoice')
->addPage()
->setFont('Helvetica', size: 12)
->cell(width: 0, height: 10, text: 'Hello World')
->save('/output/invoice.pdf');HasMetadata
문서 수준 메타데이터(Title, Author, Subject, Keywords, Creator) 설정 메서드.
setTitle(string $title): static
문서 제목을 설정합니다 (PDF 뷰어 제목 표시줄 및 XMP dc:title에 표시됨).
setAuthor(string $author): static
문서 작성자를 설정합니다 (XMP dc:creator).
setSubject(string $subject): static
문서 주제를 설정합니다 (XMP dc:description).
setKeywords(string|array $keywords): static
문서 키워드를 설정합니다. 쉼표로 구분된 문자열 또는 문자열 배열을 받습니다.
setCreator(string $creator): static
제작 애플리케이션 이름을 설정합니다 (XMP xmp:CreatorTool). 기본값은 'TCPDF-Next'입니다.
HasPages
페이지 추가, 삭제, 이동, 구성 메서드.
addPage(?PageSize $pageSize = null, ?Orientation $orientation = null): static
새 페이지를 추가합니다. 이 페이지에만 기본 페이지 크기와 방향을 선택적으로 재정의할 수 있습니다.
deletePage(int $pageNumber): static
지정된 1-기반 인덱스의 페이지를 제거합니다. 페이지가 존재하지 않으면 OutOfRangeException을 발생시킵니다.
movePage(int $from, int $to): static
한 위치에서 다른 위치로 페이지를 이동합니다. 두 인덱스 모두 1-기반입니다.
copyPage(int $pageNumber): static
페이지를 복제하고 마지막 페이지 뒤에 사본을 추가합니다.
setAutoPageBreak(bool $auto, float $margin = 0): static
자동 페이지 나누기를 활성화 또는 비활성화합니다. 활성화되면 콘텐츠가 하단 여백에서 지정된 여백 값을 뺀 위치에 도달할 때 새 페이지가 추가됩니다.
setMargins(float $left, float $top, float $right = -1, float $bottom = -1): static
사용자 단위로 페이지 여백을 설정합니다. right가 -1이면 left를 미러링합니다. bottom이 -1이면 top을 미러링합니다.
setLeftMargin(float $margin): static
왼쪽 여백만 설정합니다.
setTopMargin(float $margin): static
상단 여백만 설정합니다.
setRightMargin(float $margin): static
오른쪽 여백만 설정합니다.
setCellPadding(float $padding): static
사용자 단위로 기본 내부 셀 패딩을 설정합니다.
setPageSize(PageSize $size): static
새 페이지의 기본 페이지 크기를 설정합니다.
setOrientation(Orientation $orientation): static
새 페이지의 기본 페이지 방향을 설정합니다.
pageCount(): int
문서의 총 페이지 수를 반환합니다.
currentPage(): int
현재 페이지 번호(1-기반)를 반환합니다.
setPage(int $pageNumber): static
커서를 기존 페이지로 이동합니다.
HasTypography
폰트 선택, 크기, 간격, 문자열 측정 메서드.
setFont(string $family, string $style = '', float $size = 0): static
패밀리 이름으로 폰트를 선택합니다. 스타일은 '' (레귤러), 'B' (볼드), 'I' (이탤릭), 또는 'BI'입니다. 크기 0은 현재 크기를 유지합니다.
setFontSize(float $size): static
포인트 단위로 폰트 크기를 설정합니다.
setFontSpacing(float $spacing): static
사용자 단위로 추가 문자 간격을 설정합니다.
setFontStretching(float $percent): static
백분율로 수평 폰트 스케일링을 설정합니다 (100 = 보통).
getStringWidth(string $text, string $family = '', string $style = '', float $size = 0): float
지정된 (또는 현재) 폰트 설정을 사용하여 사용자 단위로 문자열 너비를 계산합니다.
getCharWidth(string $char): float
사용자 단위로 단일 문자의 너비를 반환합니다.
getNumberOfLines(string $text, float $width): int
지정된 너비에서 텍스트가 차지할 줄 수를 추정합니다.
HasColors
드로우, 채우기, 텍스트 색상 설정 메서드(선택적 알파 투명도 포함).
setDrawColor(int $r, int $g = -1, int $b = -1): static
스트로크(드로우) 색상을 설정합니다. 그레이스케일은 단일 값, RGB는 세 값을 전달합니다.
setFillColor(int $r, int $g = -1, int $b = -1): static
도형 및 셀 배경의 채우기 색상을 설정합니다.
setTextColor(int $r, int $g = -1, int $b = -1): static
텍스트 색상을 설정합니다.
setAlpha(float $alpha, string $blendMode = 'Normal'): static
알파 투명도(0.0 = 완전 투명, 1.0 = 완전 불투명) 및 선택적 블렌드 모드를 설정합니다.
setDrawColorObject(Color $color): static
Color 값 객체를 사용하여 스트로크 색상을 설정합니다 (RGB, CMYK, Gray, Spot 지원).
setFillColorObject(Color $color): static
Color 값 객체를 사용하여 채우기 색상을 설정합니다.
setTextColorObject(Color $color): static
Color 값 객체를 사용하여 텍스트 색상을 설정합니다.
HasTextOutput
페이지에 텍스트 콘텐츠를 렌더링하는 메서드.
cell(float $width, float $height = 0, string $text = '', string|int $border = 0, int $ln = 0, Alignment $align = Alignment::Left, bool $fill = false, string $link = ''): static
단일 줄 셀을 출력합니다. 셀은 테두리, 배경 채우기, 선택적 하이퍼링크를 가질 수 있습니다.
multiCell(float $width, float $height, string $text, string|int $border = 0, Alignment $align = Alignment::Justified, bool $fill = false, int $maxLines = 0): static
자동 줄 바꿈이 있는 여러 줄 텍스트 블록을 출력합니다.
text(float $x, float $y, string $text): static
정확한 좌표에 텍스트 문자열을 배치합니다. 줄 바꿈이나 셀 경계가 없습니다.
write(float $height, string $text, string $link = ''): static
현재 위치에서 흐르는 텍스트를 작성합니다. 인라인 하이퍼링크를 지원합니다.
writeHtml(string $html, bool $lineBreak = true, bool $fill = false, bool $resetStyles = false, string $align = ''): static
CSS 지원이 있는 HTML 문자열을 렌더링합니다. 일반적인 HTML 태그, 테이블, 목록, 인라인 스타일을 지원합니다.
writeHtmlCell(float $width, float $height, float $x, float $y, string $html, string|int $border = 0, int $ln = 0, bool $fill = false): static
위치가 지정된 셀 내부에 HTML을 렌더링합니다.
ln(float $height = 0): static
줄 바꿈을 삽입합니다. height가 0이면 마지막으로 출력된 셀의 높이를 사용합니다.
HasDrawing
선, 도형, 화살표를 그리는 메서드.
line(float $x1, float $y1, float $x2, float $y2): static
두 점 사이에 직선을 그립니다.
rect(float $x, float $y, float $w, float $h, string $style = ''): static
사각형을 그립니다. 스타일: '' (스트로크), 'F' (채우기), 'DF' (스트로크 + 채우기).
roundedRect(float $x, float $y, float $w, float $h, float $r, string $roundCorner = '1111', string $style = ''): static
모서리가 둥근 사각형을 그립니다. roundCorner 비트마스크는 어떤 모서리를 둥글게 할지 제어합니다.
circle(float $x, float $y, float $r, string $style = '', array $angles = [0, 360]): static
중심 (x, y)과 반지름 r로 원(또는 호)을 그립니다.
ellipse(float $x, float $y, float $rx, float $ry, float $angle = 0, string $style = ''): static
중심 (x, y), 수평 반지름 rx, 수직 반지름 ry로 타원을 그립니다.
polygon(array $points, string $style = ''): static
[x, y] 좌표 쌍 배열로 다각형을 그립니다.
arrow(float $x1, float $y1, float $x2, float $y2, int $headStyle = 0, float $armSize = 5, int $armAngle = 15): static
화살표 머리가 있는 선을 그립니다.
curve(float $x0, float $y0, float $x1, float $y1, float $x2, float $y2, float $x3, float $y3, string $style = ''): static
3차 베지어 곡선을 그립니다.
setLineWidth(float $width): static
스트로크 작업의 선 너비를 설정합니다.
setLineCap(int $style): static
선 끝 스타일을 설정합니다: 0 (butt), 1 (round), 2 (square).
setLineJoin(int $style): static
선 연결 스타일을 설정합니다: 0 (miter), 1 (round), 2 (bevel).
HasTransforms
좌표계 변환 메서드(스택으로 저장됨).
startTransform(): static
현재 그래픽 상태를 저장합니다. stopTransform()과 쌍으로 사용해야 합니다.
stopTransform(): static
이전에 저장한 그래픽 상태를 복원합니다.
rotate(float $angle, float $x = null, float $y = null): static
주어진 각도(도)만큼 점 (x, y)를 중심으로 이후 드로잉 작업을 회전합니다.
scale(float $sx, float $sy, float $x = null, float $y = null): static
이후 드로잉 작업을 스케일링합니다. 100 = 변경 없음, 200 = 2배 크기.
translate(float $tx, float $ty): static
이후 드로잉 작업을 (tx, ty) 사용자 단위만큼 이동(시프트)합니다.
skew(float $angleX, float $angleY, float $x = null, float $y = null): static
주어진 각도(도)만큼 이후 드로잉 작업을 기울입니다.
mirror(string $axis, float $x = null, float $y = null): static
주어진 축을 따라 이후 드로잉 작업을 미러링합니다 ('H' 수평, 'V' 수직).
HasLayout
머리글, 바닥글, 컬럼, 소책자 모드 메서드.
setHeaderCallback(callable $callback): static
모든 페이지 상단에서 호출되는 콜백을 등록합니다. Document 인스턴스를 받습니다.
setFooterCallback(callable $callback): static
모든 페이지 하단에서 호출되는 콜백을 등록합니다. Document 인스턴스를 받습니다.
setColumnsArray(array $columns): static
멀티 컬럼 레이아웃을 정의합니다. 각 항목은 'width'와 선택적 'margin' 키가 있는 연관 배열입니다.
selectColumn(int $column = 0): static
지정된 컬럼(0-기반)으로 커서를 이동합니다.
setBooklet(bool $enable, float $innerMargin = -1, float $outerMargin = -1): static
구성 가능한 안쪽 및 바깥쪽 여백으로 소책자(중철 제본) 모드를 활성화합니다.
setPrintHeader(bool $print): static
이후 페이지에서 머리글을 활성화 또는 비활성화합니다.
setPrintFooter(bool $print): static
이후 페이지에서 바닥글을 활성화 또는 비활성화합니다.
HasNavigation
북마크, 목차, 링크, 주석, 파일 첨부 메서드.
bookmark(string $title, int $level = 0, float $y = -1, int $page = 0, string $style = '', Color $color = null): static
북마크(아웃라인 항목)를 추가합니다. 레벨 0은 최상위; 더 높은 값은 중첩된 자식을 생성합니다.
addTOC(int $page = 0, string $numberFormat = '', string $filler = '.'): static
모든 북마크에서 목차를 생성하고 지정된 페이지에 삽입합니다.
addLink(): int
내부 링크 목적지를 생성하고 식별자를 반환합니다.
setLink(int $linkId, float $y = 0, int $page = -1): static
이전에 생성한 내부 링크의 목적지를 설정합니다.
annotation(float $x, float $y, float $w, float $h, string $text, array $options = []): static
지정된 사각형에 텍스트 주석을 추가합니다.
addFileAttachment(string $filePath, string $description = '', string $name = ''): static
문서에 파일을 첨부합니다. PDF/A-3 관련 파일을 지원합니다.
HasInteractive
AcroForm 폼 필드 및 JavaScript 메서드.
textField(string $name, float $x, float $y, float $w, float $h, array $options = []): static
지정된 위치에 텍스트 입력 필드를 추가합니다.
checkboxField(string $name, float $x, float $y, float $size = 10, bool $checked = false): static
체크박스 필드를 추가합니다.
radioField(string $name, float $x, float $y, float $size = 10, array $options = []): static
이름이 지정된 그룹의 일부로 라디오 버튼 필드를 추가합니다.
listboxField(string $name, float $x, float $y, float $w, float $h, array $items, array $options = []): static
리스트박스 선택 필드를 추가합니다.
comboboxField(string $name, float $x, float $y, float $w, float $h, array $items, array $options = []): static
드롭다운 콤보박스 필드를 추가합니다.
buttonField(string $name, float $x, float $y, float $w, float $h, string $caption, string $action = ''): static
선택적 JavaScript 액션이 있는 푸시 버튼 필드를 추가합니다.
includeJS(string $script): static
문서 수준 JavaScript 액션을 임베딩합니다. 문서를 열 때 실행됩니다.
HasSecurity
암호화 및 디지털 서명 메서드.
setProtection(array $permissions = [], string $userPassword = '', string $ownerPassword = '', int $mode = 3): static
AES-256(모드 3)으로 문서를 암호화합니다. 권한: 'print', 'copy', 'modify', 'annot-forms' 등.
setSignature(string $certFile, string $privateKeyFile, string $password = '', string $extracertsFile = '', int $certType = 2, array $info = []): static
PAdES 디지털 서명을 적용합니다. PKCS#12(.p12/.pfx) 파일은 certType 2를 사용합니다.
HasOutput
최종 PDF를 렌더링하는 메서드.
save(string $path): bool
PDF를 파일에 씁니다. 성공하면 true를 반환합니다.
output(OutputDestination $destination = OutputDestination::String, string $filename = 'doc.pdf', string $path = ''): string|bool
선택한 대상으로 PDF를 렌더링합니다: String (바이너리 반환), File, Inline (브라우저), 또는 Download.
toString(): string
output(OutputDestination::String)의 편의 별칭. 원시 PDF 바이너리를 반환합니다.
참고
- API 개요 -- 모든 패키지 한눈에 보기
- 열거형 레퍼런스 -- Orientation, Alignment, OutputDestination 등
- 인터페이스 레퍼런스 -- Document 클래스가 구현하는 계약
- 값 객체 API -- PageSize, Margin, Position, Dimension, Unit