값 객체 API
TCPDF-Next의 모든 값 객체는 불변입니다. 모든 "수정자" 메서드는 원본을 변경하지 않고 새 인스턴스를 반환합니다. 이는 공유된 변경 가능 상태로 인한 버그 범주를 제거합니다.
PageSize
네임스페이스: TcpdfNext\ValueObjects\PageSize
페이지의 치수를 나타냅니다. 내부적으로 모든 측정값은 PDF 포인트(1/72 인치)로 저장됩니다.
팩토리 메서드 (ISO A 시리즈)
PageSize::a0(): static
841 x 1189 mm
PageSize::a1(): static
594 x 841 mm
PageSize::a2(): static
420 x 594 mm
PageSize::a3(): static
297 x 420 mm
PageSize::a4(): static
210 x 297 mm (기본값)
PageSize::a5(): static
148 x 210 mm
PageSize::a6(): static
105 x 148 mm
팩토리 메서드 (ISO B 시리즈)
PageSize::b0(): static
1000 x 1414 mm
PageSize::b1(): static
707 x 1000 mm
PageSize::b2(): static
500 x 707 mm
PageSize::b3(): static
353 x 500 mm
PageSize::b4(): static
250 x 353 mm
PageSize::b5(): static
176 x 250 mm
팩토리 메서드 (북미)
PageSize::letter(): static
8.5 x 11 in (215.9 x 279.4 mm)
PageSize::legal(): static
8.5 x 14 in (215.9 x 355.6 mm)
PageSize::tabloid(): static
11 x 17 in (279.4 x 431.8 mm)
커스텀 및 조회
PageSize::fromMm(float $width, float $height, string $name = 'Custom'): static
밀리미터 치수에서 페이지 크기를 생성합니다.
PageSize::fromPoints(float $width, float $height, string $name = 'Custom'): static
포인트 치수에서 페이지 크기를 생성합니다.
PageSize::fromName(string $name): static
이름으로 표준 페이지 크기를 조회합니다(대소문자 구분 없음). 알 수 없는 이름은 InvalidArgumentException을 발생시킵니다.
방향 헬퍼
landscape(): static
너비 > 높이가 되도록 너비와 높이가 교환된 새 PageSize를 반환합니다.
portrait(): static
높이 > 너비가 되도록 너비와 높이가 교환된 새 PageSize를 반환합니다.
속성
| 속성 | 타입 | 설명 |
|---|---|---|
$width | float | 포인트 단위의 너비 |
$height | float | 포인트 단위의 높이 |
$name | string | 사람이 읽을 수 있는 이름 (예: 'A4', 'Letter') |
편의 메서드
widthMm(): float
밀리미터 단위의 너비를 반환합니다.
heightMm(): float
밀리미터 단위의 높이를 반환합니다.
예제
php
use TcpdfNext\ValueObjects\PageSize;
$a4 = PageSize::a4();
$landscape = $a4->landscape(); // 297 x 210 mm
$custom = PageSize::fromMm(140, 216, 'Half Letter');
$letter = PageSize::fromName('Letter');Margin
네임스페이스: TcpdfNext\ValueObjects\Margin
4면 페이지 여백을 나타냅니다. 내부 저장소는 PDF 포인트입니다.
팩토리 메서드
Margin::mm(float $top, float $right, float $bottom, float $left): static
밀리미터 값에서 여백을 생성합니다.
Margin::pt(float $top, float $right, float $bottom, float $left): static
포인트 값에서 여백을 생성합니다.
Margin::uniform(float $value): static
네 면 모두 동일(포인트).
Margin::uniformMm(float $value): static
네 면 모두 동일(밀리미터).
Margin::symmetric(float $horizontal, float $vertical): static
대칭 여백(horizontal = 좌 + 우, vertical = 상 + 하) 포인트.
Margin::zero(): static
모든 여백을 0으로 설정합니다.
속성
| 속성 | 타입 | 설명 |
|---|---|---|
$top | float | 포인트 단위의 상단 여백 |
$right | float | 포인트 단위의 오른쪽 여백 |
$bottom | float | 포인트 단위의 하단 여백 |
$left | float | 포인트 단위의 왼쪽 여백 |
수정자 메서드
withTop(float $value): static
상단 값이 대체된 새 Margin을 반환합니다(포인트).
withRight(float $value): static
오른쪽 값이 대체된 새 Margin을 반환합니다.
withBottom(float $value): static
하단 값이 대체된 새 Margin을 반환합니다.
withLeft(float $value): static
왼쪽 값이 대체된 새 Margin을 반환합니다.
계산 메서드
printableArea(PageSize $pageSize): Dimension
인쇄 가능한 Dimension(페이지 크기에서 여백을 뺀 값)을 반환합니다.
예제
php
use TcpdfNext\ValueObjects\Margin;
use TcpdfNext\ValueObjects\PageSize;
$margin = Margin::mm(top: 15, right: 20, bottom: 15, left: 20);
$narrow = $margin->withLeft(36.0)->withRight(36.0);
$area = $margin->printableArea(PageSize::a4());
echo $area->widthMm(); // 170.0Position
네임스페이스: TcpdfNext\ValueObjects\Position
PDF 포인트 단위의 불변 x--y 좌표 쌍.
팩토리 메서드
new Position(float $x, float $y)
포인트 값에서 생성합니다.
Position::mm(float $x, float $y): static
밀리미터 값에서 생성합니다(내부적으로 포인트로 변환).
속성
| 속성 | 타입 | 설명 |
|---|---|---|
$x | float | 포인트 단위의 수평 좌표 |
$y | float | 포인트 단위의 수직 좌표 |
메서드
translate(float $dx, float $dy): static
(dx, dy) 포인트만큼 이동한 새 Position을 반환합니다.
xMm(): float
밀리미터 단위의 x를 반환합니다.
yMm(): float
밀리미터 단위의 y를 반환합니다.
예제
php
use TcpdfNext\ValueObjects\Position;
$pos = Position::mm(x: 25.4, y: 50.8);
$shifted = $pos->translate(dx: 10, dy: 20);
echo $shifted->xMm(); // ~28.9Dimension
네임스페이스: TcpdfNext\ValueObjects\Dimension
PDF 포인트 단위의 불변 너비--높이 쌍.
팩토리 메서드
new Dimension(float $width, float $height)
포인트 값에서 생성합니다.
Dimension::mm(float $width, float $height): static
밀리미터 값에서 생성합니다.
속성
| 속성 | 타입 | 설명 |
|---|---|---|
$width | float | 포인트 단위의 너비 |
$height | float | 포인트 단위의 높이 |
메서드
swap(): static
너비와 높이가 교환된 새 Dimension을 반환합니다.
widthMm(): float
밀리미터 단위의 너비를 반환합니다.
heightMm(): float
밀리미터 단위의 높이를 반환합니다.
area(): float
제곱 포인트 단위의 면적을 반환합니다.
예제
php
use TcpdfNext\ValueObjects\Dimension;
$dim = Dimension::mm(width: 210, height: 297);
echo $dim->width; // 595.28
echo $dim->widthMm(); // 210.0
$swapped = $dim->swap(); // 297 x 210 mm 동등Unit
네임스페이스: TcpdfNext\ValueObjects\Unit
측정 단위 간 변환을 위한 정적 유틸리티 클래스. 모든 변환은 인치당 72포인트의 PDF 표준에 기반합니다.
변환 메서드
Unit::mm(float $value): float
밀리미터를 포인트로 변환합니다. mmToPoints()의 별칭.
Unit::pt(float $value): float
항등 -- 값을 변경하지 않고 반환합니다(API 일관성을 위해).
Unit::cm(float $value): float
센티미터를 포인트로 변환합니다.
Unit::in(float $value): float
인치를 포인트로 변환합니다 (값 x 72).
Unit::mmToPoints(float $mm): float
밀리미터를 포인트로 변환합니다 (mm x 72 / 25.4).
Unit::pointsToMm(float $pt): float
포인트를 밀리미터로 변환합니다 (pt x 25.4 / 72).
Unit::inchesToPoints(float $inches): float
인치를 포인트로 변환합니다 (inches x 72).
Unit::pointsToInches(float $pt): float
포인트를 인치로 변환합니다 (pt / 72).
Unit::cmToPoints(float $cm): float
센티미터를 포인트로 변환합니다 (cm x 72 / 2.54).
Unit::pointsToCm(float $pt): float
포인트를 센티미터로 변환합니다 (pt x 2.54 / 72).
Unit::convert(float $value, string $from, string $to): float
범용 변환기. 지원되는 단위 문자열: 'mm', 'cm', 'in', 'pt'.
예제
php
use TcpdfNext\ValueObjects\Unit;
$points = Unit::mmToPoints(210.0); // 595.28
$mm = Unit::pointsToMm(595.28); // 210.0
$points = Unit::inchesToPoints(8.5); // 612.0
$result = Unit::convert(1.0, 'in', 'mm'); // 25.4Color
네임스페이스: TcpdfNext\Graphics\Color
여러 색상 공간을 지원하는 불변 색상 표현. Color는 Graphics 패키지에 있지만, 라이브러리 전체에서 광범위하게 사용됩니다(텍스트 색상, 드로우 색상, 채우기 색상, 북마크 색상, 주석 색상).
팩토리 메서드
Color::rgb(int $r, int $g, int $b): static
DeviceRGB 색상을 생성합니다. 값 범위는 0~255입니다.
Color::cmyk(float $c, float $m, float $y, float $k): static
DeviceCMYK 색상을 생성합니다. 값 범위는 0~100입니다.
Color::gray(int $level): static
DeviceGray 색상을 생성합니다. 레벨 범위는 0(검정)~255(흰색)입니다.
Color::spot(string $name, Color $fallback, float $tint = 100): static
프로세스 색상 대체 및 틴트 비율이 있는 명명된 별색(Separation) 색상을 생성합니다.
Color::hex(string $hex): static
3자리 또는 6자리 hex 문자열('#' 포함 또는 미포함)에서 색상을 생성합니다.
Color::black(): static
편의: rgb(0, 0, 0).
Color::white(): static
편의: rgb(255, 255, 255).
Color::transparent(): static
편의: 완전 투명 색상.
속성
| 속성 | 타입 | 설명 |
|---|---|---|
$space | ColorSpace | 색상 공간 enum (DeviceRGB, DeviceCMYK, DeviceGray, Separation) |
메서드
toRgbArray(): array
0--255 값의 [r, g, b]를 반환합니다. 필요 시 CMYK 또는 Gray에서 변환합니다.
toCmykArray(): array
0--100 값의 [c, m, y, k]를 반환합니다.
toHex(): string
6자리 hex 문자열을 반환합니다(예: 'ff6600').
withAlpha(float $alpha): static
지정된 알파(0.0--1.0)를 가진 새 Color를 반환합니다.
equals(Color $other): bool
두 색상의 값 동등성을 비교합니다.
예제
php
use TcpdfNext\Graphics\Color;
$brand = Color::hex('#0066CC');
$print = Color::cmyk(100, 0, 0, 0);
$spot = Color::spot('PANTONE 286 C', Color::cmyk(100, 66, 0, 2));
$faded = $brand->withAlpha(0.5);
echo $brand->toHex(); // '0066cc'참고
- API 개요 -- 모든 패키지 한눈에 보기
- Document API -- 이 값 객체를 받는 메서드
- 열거형 레퍼런스 -- ColorSpace, Orientation 및 기타 관련 열거형
- 값 객체 가이드 -- 개념적 개요 및 고급 패턴