ValueObjects: 도메인 기본 요소 + 단위

한눈에 보기

ValueObjects 모듈은 엔진이 주고받는 불변 기하 기본 요소를 담고 있습니다: PageSize, Dimension, Position, Margin, 그리고 Unit enum입니다. 각각은 final readonly 클래스이므로 인스턴스를 자유롭게 공유할 수 있으며, 변환은 새 인스턴스를 반환합니다.

설치

composer require nextpdf/core:^3

개념 개요

네 값 객체는 모두 final readonly입니다. float 좌표를 담으며 변경자(mutator)를 노출하지 않습니다. 변환 메서드는 명명 인수로 새 인스턴스를 다시 구성합니다. 따라서 방어적 복사 없이도 캐시하고, 문서 간에 전달하고, 워커 간에 공유하기에 안전합니다.

**PageSize**는 너비, 높이(포인트 단위, 1 pt = 1/72 인치), 이름을 저장합니다. 정적 팩터리는 ISO 216 A 시리즈(A0–A6), ISO 216 B 시리즈(B0–B5), 그리고 북미 규격(Letter, Legal, Tabloid)을 제공합니다. A/B 치수는 ISO 216에서 정의한 재단 용지 크기 시리즈를 따릅니다. fromName()은 대소문자를 구분하지 않고 이름을 해석하며, 알 수 없는 이름에 대해서는 PageLayoutException을 던집니다. landscape()와 portrait()는 방향 변형을 반환합니다(이미 해당 방향이면 self를 변경 없이 반환합니다). toDimension()은 포인트 단위의 Dimension으로 변환합니다.

**Dimension**은 너비, 높이, 그리고 Unit을 저장합니다. 팩터리(fromMillimeters(), fromPoints(), fromInches())는 주어진 단위로 구성합니다. toPoints()와 toMillimeters()는 값을 변환합니다(이미 포인트 단위이면 self를 반환). withWidth()와 withHeight()는 크기가 조정된 복사본을 반환합니다. 변환은 정확한 계수를 사용합니다: 밀리미터당 72/25.4 포인트, 센티미터당 72/2.54, 인치당 72.

**Position**은 PDF 사용자 공간의 2D 점(x, y)입니다. origin()은 (0, 0)을 반환합니다. translate(dx, dy)는 오프셋이 적용된 복사본을 반환합니다. withX() / withY()는 한 축만 교체된 복사본을 반환합니다.

**Margin**은 top, right, bottom, left를 보유합니다. 팩터리: uniform()(모든 변에 같은 값), symmetric(vertical, horizontal), 그리고 zero().

**Unit**은 문자열 기반 enum입니다 — Point (pt), Millimeter (mm), Centimeter (cm), Inch (in) — 그리고 toPointFactor()는 포인트로 변환하는 곱셈 계수를 반환합니다.

API 표면

심볼	종류	주요 멤버
`NextPDF\ValueObjects\PageSize`	final readonly class	`$width`, `$height`, `$name`; 팩터리 `A0`–`A6`, `B0`–`B5`, `Letter`, `Legal`, `Tabloid`; `fromName()`, `landscape()`, `portrait()`, `toDimension()`
`NextPDF\ValueObjects\Dimension`	final readonly class	`$width`, `$height`, `$unit`; `fromMillimeters()`, `fromPoints()`, `fromInches()`, `toPoints()`, `toMillimeters()`, `withWidth()`, `withHeight()`
`NextPDF\ValueObjects\Position`	final readonly class	`$x`, `$y`; `origin()`, `translate()`, `withX()`, `withY()`
`NextPDF\ValueObjects\Margin`	final readonly class	`$top`, `$right`, `$bottom`, `$left`; `uniform()`, `symmetric()`, `zero()`
`NextPDF\ValueObjects\Unit`	string enum	`Point`, `Millimeter`, `Centimeter`, `Inch`; `toPointFactor()`

코드 샘플 — 빠른 시작

팩터리로 기하 기본 요소를 구성합니다.

<?php

declare(strict_types=1);

use NextPDF\ValueObjects\Margin;
use NextPDF\ValueObjects\PageSize;
use NextPDF\ValueObjects\Position;

$page = PageSize::A4();                       // 595.276 x 841.890 pt
$margin = Margin::uniform(18.0);              // 18 pt all sides
$origin = Position::origin()->translate(72.0, 72.0); // 1 inch in from corner

코드 샘플 — 프로덕션

단위를 변환하고, 방향을 도출하고, 여백을 구성으로 전달합니다.

<?php

declare(strict_types=1);

use NextPDF\Core\Config;
use NextPDF\ValueObjects\Dimension;
use NextPDF\ValueObjects\Margin;
use NextPDF\ValueObjects\PageSize;

// A label sized in millimeters, resolved to points for the engine.
$label = Dimension::fromMillimeters(width: 100.0, height: 150.0)->toPoints();

$page = PageSize::A4()->landscape();   // swap to width >= height
$margin = Margin::symmetric(vertical: 20.0, horizontal: 15.0);

$config = (new Config())
    ->withPageSize($page)
    ->withMargins($margin);

// $label->width / $label->height are now in points for downstream layout.

엣지 케이스 및 주의사항

모든 치수는 Dimension으로 감싸 명시적인 Unit을 지정하지 않는 한 포인트로 해석됩니다. Config 여백은 기본적으로 포인트입니다.
PageSize::landscape() / portrait()는 방향이 이미 일치하는 경우 동일한 인스턴스를 반환합니다 — 새 할당 없이 아이덴티티가 보존됩니다.
PageSize::fromName()은 대소문자를 구분하지 않지만, 명명된 팩터리만 해석합니다. 알 수 없는 이름은 기본 크기가 아니라 PageLayoutException을 던집니다.
Dimension::toPoints()는 단위가 이미 Point인 경우 self를 반환합니다. 새 객체라고 가정하지 마십시오.
이 객체들은 원시 float 값을 담으며 범위 검증을 수행하지 않습니다. 음수 또는 0인 치수도 생성 시점에 허용됩니다. 기하 유효성은 여기가 아니라 레이아웃 계층과 라이터 계층에서 강제됩니다.
부동소수점 변환은 정확한 유리수 계수(72/25.4, 72/2.54)를 사용합니다. 재현 가능한 출력을 안정적으로 유지하려면 표현 경계에서만 반올림하십시오.

성능

모든 값 객체는 float로 이루어진 평면 readonly 구조체입니다. 중첩된 가변 상태가 없으므로 생성과 각 변환은 깊은 복사가 없는 O(1) 단일 할당입니다. 문서 간에 인스턴스를 공유하는 데 추가 비용은 들지 않습니다. 이 참조 페이지의 기본 performance_budget은 wall_ms: 1500, peak_mb: 64입니다.

보안 참고사항

이 값 객체들은 I/O가 없고, 페이지 크기 이름 외에 사용자가 제공한 문자열이 없으며, 외부 리소스 핸들도 없으므로 직접적인 공격 표면을 노출하지 않습니다. PageSize::fromName()은 알 수 없는 입력을 조용히 폴백하지 않고 예외로 거부하므로, 잘못된 구성이 예상치 못한 페이지 기하를 만들어 내는 대신 명확하게 드러나도록 유지합니다.

적합성

규격	조항	주제
ISO 216:2007	A / B 시리즈	다음 팩터리의 재단 용지 크기 치수: `A` / `B` (의역; ISO 원문 인용 없음, 청크 고정 없음)

A 및 B 팩터리의 치수는 포인트로 표현된 ISO 216 재단 크기에 대응합니다. 북미 규격(Letter, Legal, Tabloid)은 ISO에 근거하지 않는 사실상의 업계 규격입니다. ISO 참조는 사이트 인용 정책에 따라 의역되었습니다. 원문 그대로의 청크는 고정되어 있지 않습니다.

함께 보기

/modules/core/config/ — Config가 사용하는 PageSize와 Margin
/modules/core/layout/ — 이 기본 요소들을 사용하는 기하 처리 구성 요소
/modules/core/graphics/ — Position(드로잉 좌표 공간에서)
/modules/core/contracts/ — Orientation과 짝을 이루는 PageSize
/modules/core/exception/ — fromName()에서 발생하는 PageLayoutException