열거형 레퍼런스

한눈에 보기

여러 NextPDF 작성 메서드는 단순한 문자열이나 정수가 아니라 타입이 지정된 enum을 받습니다. 열거형이 곧 계약입니다. 그것은 인수를 고정된 유효 집합으로 제약하며, IDE와 PHPStan은 그 밖의 어떤 값도 거부합니다. 이 페이지는 공개 Document 및 Config API를 통해 설정하거나(또는 받는) 열거형에 대한 허용 값 조회표이며, 여기에 엔진 수준 색상 열거형 하나(RenderingIntent)가 더해집니다. 이는 그 케이스들이 공개 색상 계약의 일부이기 때문에 포함되었고, 등장하는 곳에서 엔진 수준으로 표시됩니다.

이는 구성 레퍼런스의 동반 문서입니다. Config 객체가 어떤 노브를 돌릴지 알려 준다면, 이 페이지는 그 노브가 어떤 값을 받는지 알려 줍니다. 각 항목은 열거형의 정규화된 클래스 이름(FQCN), 백킹 타입, 소스에서 복사한 정확한 케이스 목록, 그리고 그것을 받는 공개 메서드를 나열합니다.

깊은 엔진 내부 열거형(HTML/CSS 레이아웃, 추상 구문 트리, CLI, 셰이퍼 내부)은 의도적으로 제외됩니다 — 그것들은 결코 설정하지 않습니다. 아래 거의 모든 것은 공개 API를 통해 전달하는 값입니다. 유일한 예외인 RenderingIntent는 공개 세터가 없는 엔진 수준 색상 열거형이며, 완전성을 위해 나열되고 등장하는 곳에서 그렇게 표시됩니다.

백킹 타입

PHP 열거형은 두 가지 형태로 나뉘며, 그 형태가 값을 작성하는 방식을 바꿉니다.

백킹된(backed) 열거형(enum X: string 또는 enum X: int)은 모든 케이스에 스칼라 value를 가지므로, X::from('...') / $case->value를 통해 왕복합니다. 여기 대부분의 열거형은 백킹됩니다.
순수(pure) 열거형(백킹 타입이 없는 enum X)은 케이스는 있지만 스칼라 값이 없습니다. 항상 케이스로 참조합니다(X::SomeCase). UnderlineStyle만 순수입니다.

두 형태 모두 케이스 자체를 전달합니다 — 예를 들어 $pdf->addPage(orientation: Orientation::Landscape). 백킹 타입은 선택을 직렬화하거나 구성에서 다시 읽어야 할 때만 중요합니다.

페이지 설정

Orientation

세로 또는 가로 페이지 기하 구조입니다. 페이지를 추가할 때 전달됩니다. 엔진이 너비와 높이를 맞춰 교환합니다.

속성	값
FQCN	`NextPDF\Contracts\Orientation`
Backing	`string`
Set via	`Document::addPage(?PageSize $size = null, Orientation $orientation = Orientation::Portrait)`

Case	Backing value
`Portrait`	`'P'`
`Landscape`	`'L'`

use NextPDF\Contracts\Orientation;
use NextPDF\ValueObjects\PageSize;

$pdf->addPage(PageSize::a4(), Orientation::Landscape);

드로잉 및 그래픽

LineCap

획이 그려진 열린 경로가 어떻게 끝나는지입니다. ISO 32000-2:2020 §8.4.3.3.

속성	값
FQCN	`NextPDF\Graphics\LineCap`
Backing	`int`
Set via	`LineStyle` 구성 객체(`new LineStyle(cap: ...)`), `Document::setLineStyle(LineStyle $style)`로 적용

Case	Backing value	의미
`Butt`	`0`	끝점에서 사각형 끝, 돌출 없음.
`Round`	`1`	끝점에서 반원 호.
`Square`	`2`	끝점 너머로 선 너비의 절반만큼 연장되는 사각형 돌출.

LineJoin

획이 그려진 두 세그먼트가 모서리에서 어떻게 만나는지입니다. ISO 32000-2:2020 §8.4.3.4.

속성	값
FQCN	`NextPDF\Graphics\LineJoin`
Backing	`int`
Set via	`LineStyle` 구성 객체(`new LineStyle(join: ...)`), `Document::setLineStyle(LineStyle $style)`로 적용

Case	Backing value	의미
`Miter`	`0`	마이터 한계까지 연장된 날카로운 모서리.
`Round`	`1`	바깥쪽 가장자리를 잇는 원형 호.
`Bevel`	`2`	바깥쪽 가장자리를 잇는 대각선.

LineCap과 LineJoin은 Document 메서드에 직접 전달되지 않습니다 — 그것들은 불변 NextPDF\Graphics\LineStyle 값 객체의 필드이며, 그 객체를 setLineStyle()에 넘깁니다.

use NextPDF\Graphics\{LineStyle, LineCap, LineJoin};

$style = new LineStyle(width: 1.5, cap: LineCap::Round, join: LineJoin::Bevel);
$pdf->setLineStyle($style);
$pdf->line(20, 20, 120, 20);

BlendMode

이후 드로잉에 적용되는 투명도 혼합 함수입니다. 처음 12개 케이스는 분리 가능하고, 마지막 4개는 분리 불가능한 HSL 모드입니다. ISO 32000-2:2020 §11.3.5.

속성	값
FQCN	`NextPDF\Graphics\BlendMode`
Backing	`string`
Set via	`Document::setAlpha(float $alpha, BlendMode $mode = BlendMode::Normal)`

Case	Backing value	Case	Backing value
`Normal`	`'Normal'`	`HardLight`	`'HardLight'`
`Multiply`	`'Multiply'`	`SoftLight`	`'SoftLight'`
`Screen`	`'Screen'`	`Difference`	`'Difference'`
`Overlay`	`'Overlay'`	`Exclusion`	`'Exclusion'`
`Darken`	`'Darken'`	`Hue`	`'Hue'`
`Lighten`	`'Lighten'`	`Saturation`	`'Saturation'`
`ColorDodge`	`'ColorDodge'`	`Color`	`'Color'`
`ColorBurn`	`'ColorBurn'`	`Luminosity`	`'Luminosity'`

use NextPDF\Graphics\BlendMode;

$pdf->setAlpha(0.6, BlendMode::Multiply);
$pdf->rect(20, 20, 80, 40, 'F');

색상

RenderingIntent

색상 변환 중에 색역을 벗어난 색상이 어떻게 재매핑되는지입니다. ri 연산자로 내보내집니다. ISO 32000-2:2020 §8.6.5.8(표 71).

이 페이지의 다른 열거형과 달리, RenderingIntent에는 공개 Document 또는 Config 세터가 없습니다 — 그것은 엔진 수준 열거형입니다. 그것은 내부 드로잉 엔진(DrawingEngine::setRenderingIntent())에 직접 적용되며, 그 엔진이 현재 콘텐츠 스트림에 ri 연산자를 내보냅니다. 그 케이스들이 공개 색상 계약의 일부이기 때문에 완전성을 위해 여기 나열하지만, 이 페이지의 나머지가 문서화하는 개발자 대상 작성 API의 일부는 아닙니다. 드로잉 엔진은 프로그래밍 대상인 진입점이 아니라 내부 클래스로 취급하십시오.

속성	값
FQCN	`NextPDF\Graphics\RenderingIntent`
Backing	`string`
Set via	엔진 수준 전용 — 내부 드로잉 엔진에 적용되며, 공개 Document/`Config` 세터가 없습니다.

Case	Backing value	의미
`RelativeColorimetric`	`'RelativeColorimetric'`	색역 내 색상을 보존하고, 색역을 벗어난 것은 클리핑.
`AbsoluteColorimetric`	`'AbsoluteColorimetric'`	종이 흰색을 포함하여 측색 값을 정확히 보존.
`Saturation`	`'Saturation'`	색조/휘도를 희생하여 선명한 채도 보존.
`Perceptual`	`'Perceptual'`	시각적 관계 보존. 매끄러운 색역 압축.

OutputColorProfile

문서의 /OutputIntent에 선언된 작업 공간 색상 프로파일입니다. 기본값 DeviceRGB는 레거시 “추가 OutputIntent 없음” 동작을 보존합니다. 다른 케이스를 선택하면 작성기가 번들된 ICC 프로파일과 함께 /GTS_PDFX OutputIntent를 내보냅니다(ISO 32000-2:2020 §14.11.5). 이는 호출별 메서드가 아니라 Config 값입니다 — Document에 전달하는 구성 객체에 설정하십시오.

속성	값
FQCN	`NextPDF\Core\OutputColorProfile`
Backing	`string`
Set via	`Config::withOutputColorProfile(OutputColorProfile $profile)`(`Config` 생성자의 `$outputColorProfile` 매개변수)

Case	Backing value	비고
`DeviceRGB`	`'device-rgb'`	기본값. 추가 OutputIntent를 내보내지 않음.
`Srgb`	`'srgb'`	명시적 sRGB OutputIntent(IEC 61966-2-1). 광색역 아님.
`DisplayP3`	`'display-p3'`	Display-P3 광색역(D65).
`Rec2020`	`'rec2020'`	ITU-R BT.2020 / Rec.2020 광색역.
`A98RGB`	`'a98-rgb'`	Adobe RGB 1998.
`ProphotoRGB`	`'prophoto-rgb'`	ProPhoto RGB / ROMM RGB(D50).

use NextPDF\Core\{Config, OutputColorProfile};

$config = (new Config())->withOutputColorProfile(OutputColorProfile::DisplayP3);

텍스트

TextRenderingMode

글리프가 채워지는지, 획이 그려지는지, 클리핑되는지, 아니면 보이지 않게 렌더링되는지입니다(보이지 않는 모드는 검색 가능한 OCR 레이어의 기반입니다). ISO 32000-2:2020 §9.3.6, 표 104.

속성	값
FQCN	`NextPDF\Content\TextRenderingMode`
Backing	`int`
Set via	`Document::setTextRenderingMode(TextRenderingMode $mode)`

Case	Backing value	의미
`Fill`	`0`	글리프 채우기.
`Stroke`	`1`	글리프 외곽선 획.
`FillStroke`	`2`	채운 다음 획.
`Invisible`	`3`	보이지 않게 렌더링(검색 가능한 OCR 레이어).
`FillClip`	`4`	채우고 클리핑 경로에 추가.
`StrokeClip`	`5`	획을 그리고 클리핑 경로에 추가.
`FillStrokeClip`	`6`	채우고, 획을 그리고, 클리핑.
`Clip`	`7`	클리핑 경로에만 추가(보이는 렌더링 없음).

UnderlineStyle

밑줄 장식이 어떻게 그려지는지입니다. 여기서 유일한 순수 열거형이므로, 항상 케이스로 참조합니다.

속성	값
FQCN	`NextPDF\Contracts\UnderlineStyle`
Backing	순수(백킹 값 없음)
Set via	`Document::setUnderlineStyle(UnderlineStyle $style)`

Case	의미
`RectFill`	베이스라인 아래 채워진 사각형(TCPDF 호환 기본값).
`StrokeLine`	베이스라인 아래 획이 그려진 선(시맨틱 선 그리기).

use NextPDF\Content\TextRenderingMode;
use NextPDF\Contracts\UnderlineStyle;

$pdf->setTextRenderingMode(TextRenderingMode::Invisible); // OCR text layer
$pdf->setUnderlineStyle(UnderlineStyle::StrokeLine);

적합성

ConformanceMode

문서 수준 적합성 계약입니다. 작성기가 준수해야 할 ISO 파트, 그리고 구조적 태깅이 필요한지 여부입니다. 기본값 Plain은 제약 없는 PDF 2.0 출력입니다. ISO 14289-2:2024(PDF/UA-2)와 ISO 19005 PDF/A 파트.

속성	값
FQCN	`NextPDF\Conformance\ConformanceMode`
Backing	`string`
Set via	`Document::setConformanceMode(ConformanceMode $mode)`(저수준 비상구. 코어에서 PDF/UA-2에는 `enableTaggedPdf()`를, PDF/A에는 `enablePdfA()`(프리미엄 전용)를 선호하십시오)

Case	Backing value	계약
`Plain`	`'plain'`	PDF 2.0, 제약 없음(기본값).
`PdfUa1`	`'pdfua1'`	ISO 14289-1(Tagged PDF/UA-1).
`PdfUa2`	`'pdfua2'`	ISO 14289-2:2024(Tagged PDF/UA-2).
`PdfA2`	`'pdfa2'`	ISO 19005-2(PDF/A-2).
`PdfA3`	`'pdfa3'`	ISO 19005-3(PDF/A-3 프로파일 판별자).
`PdfA3b`	`'pdfa3b'`	ISO 19005-3 PDF/A-3b(Basic).
`PdfA3u`	`'pdfa3u'`	ISO 19005-3 PDF/A-3u(유니코드 추출 가능).
`PdfA4`	`'pdfa4'`	ISO 19005-4:2020(PDF/A-4 프로파일 판별자).
`PdfA4e`	`'pdfa4e'`	ISO 19005-4:2020 PDF/A-4e(Engineering).
`PdfA4f`	`'pdfa4f'`	ISO 19005-4:2020 PDF/A-4f(File attachments).

열거형은 판별 헬퍼 — isTagged(), isAccessibility(), isArchival(), pdfaPart() — 를 가지므로, 작성기 측 게이트가 모드를 다시 도출하지 않고 그 모드로 분기합니다.

코어 전용 빌드가 실제로 사용할 수 있는 케이스. enum 타입은 모든 케이스를 나열하지만, 케이스를 나열하는 것이 코어에서 그 적합성을 생산할 수 있다는 것과 같지는 않습니다.

코어(추가 패키지 없음): Plain, PdfUa1, PdfUa2. Tagged PDF / PDF/UA 경로는 코어에 내장되어 있습니다 — enableTaggedPdf()는 PDF/UA 작성 경로(기본적으로 PdfUa2)를 선택하고 라이선스 검사 없이 구조 트리를 연결합니다.
프리미엄 전용: 모든 PDF/A 케이스(PdfA2, PdfA3, PdfA3b, PdfA3u, PdfA4, PdfA4e, PdfA4f). 실제 PDF/A 출력은 enablePdfA()로 생산되며, 이는 프리미엄 등급 기능입니다(ADR-011). 그것은 nextpdf/pro 패키지를 필요로 하며, 그 패키지가 없으면 InvalidConfigException(“install the nextpdf/pro package”)으로 페일 클로즈드합니다.

setConformanceMode()는 판별자 필드만 작성하는 저수준 비상구입니다 — 그것은 PDF/A 기계 장치를 설치하지 않습니다. 따라서 코어 전용 빌드에서 그것을 통해 PdfA* 케이스를 설정하면, enablePdfA()가 제공하는 보관 보장 없이 문서에 라벨만 붙으므로, 프리미엄 전용 모드는 코어 전용 빌드에서 신뢰해서는 안 됩니다. 실제 적합성 경로에는 enableTaggedPdf() / enablePdfA()를 사용하고, PDF/A 산출물이 필요할 때마다 프리미엄 패키지를 사용하십시오.

use NextPDF\Conformance\ConformanceMode;

$pdf->setConformanceMode(ConformanceMode::PdfUa2);

첨부 파일

AFRelationship

임베드된 연관 파일에 대한 /AFRelationship 값입니다. 비적합 값은 PDF/A-3 및 PDF/A-4 검증을 실패시키므로, 열거형이 그것을 설정하는 안전한 방법입니다. ISO 32000-2:2020 §14.13.5(표 401).

속성	값
FQCN	`NextPDF\Navigation\AFRelationship`
Backing	`string`
Set via	`Document::embedFile(string $path, string $description = '', AFRelationship\|string $afRelationship = AFRelationship::Unspecified)`

Case	Backing value	용도
`Source`	`'Source'`	PDF가 생성된 원본 문서.
`Data`	`'Data'`	PDF가 파생된 원시 데이터(예: Factur-X / ZUGFeRD XML).
`Alternative`	`'Alternative'`	대체 표현(점자, 캡션, SVG).
`Supplement`	`'Supplement'`	보충 자료.
`EncryptedPayload`	`'EncryptedPayload'`	PDF가 감싸는 불투명한 암호화 블롭.
`FormData`	`'FormData'`	폼 데이터(XFDF, FDF, XML).
`Schema`	`'Schema'`	`Data` 파일을 설명하는 스키마(XSD, JSON Schema). PDF 2.0.
`Unspecified`	`'Unspecified'`	관계 미지정(기본값).

embedFile()은 열거형 케이스 또는 그 문자열 리터럴(앞에 슬래시가 있든 없든)을 모두 받으므로, AFRelationship::Data와 '/Data'는 동등합니다. 케이스를 전달하는 것이 타입 안전한 선택입니다.

use NextPDF\Navigation\AFRelationship;

// e-invoice payload: declare the XML as the source data
$pdf->embedFile('invoice.xml', 'Factur-X invoice data', AFRelationship::Data);

참고 항목

구성 레퍼런스 — 이 열거형들이 제약하는 값을 가진 Config 객체이며, withOutputColorProfile()을 포함합니다.
Graphics 모듈 — LineStyle, BlendMode, RenderingIntent, 그리고 드로잉 엔진.
Typography 모듈 — 텍스트 렌더링과 밑줄 장식.
Conformance 모듈 — ConformanceMode 판별자와 PDF/UA / PDF/A 활성화 경로.
Navigation 모듈 — 연관 파일과 /AF 메커니즘.
레퍼런스 색인 — API, 구성, 호환성 레퍼런스 자료의 진입점.