Config: 불변 문서 구성

한눈에 보기

Config는 불변 문서 구성 객체입니다. 설정을 변경할 때마다 타입 지정 wither가 새 인스턴스를 반환하므로, 구성은 여러 문서와 워커 사이에서 안전하게 공유할 수 있습니다. NextPdfConfig는 프로세스 전역 CSS 파서의 안전 한도를 보유하는 별도의 정적 클래스입니다.

설치

composer require nextpdf/core:^3

두 클래스 모두 core 패키지에 포함되어 있습니다. Config는 1.7.0부터 존재했습니다. NextPdfConfig는 2.2.0부터 존재했습니다.

개념 개요

Config는 final readonly 클래스이며 #[DisallowDynamicProperties]로 표시됩니다. 이 클래스는 스칼라와 final readonly 값 객체만 보유하므로, 전체 그래프가 깊은 수준까지 불변으로 유지됩니다. 일반적인 with(string, mixed) 세터는 없습니다. 각 변경마다 전용 타입 wither가 있습니다. 그 수는 19개이며 — withPageSize(), withMargins(), withCompress()부터 withOutputColorProfile()까지 — 각각 명명된 인수로 객체를 재구성합니다. 명명된 인수를 사용한 재구성은 의도적입니다. 생성자 매개변수가 추가되더라도 기존 wither에서 위치 인수가 조용히 밀려나는 일은 결코 없습니다. 호환성 테스트는 리플렉션으로 공개 메서드 목록과 매개변수 개수를 고정합니다. 시그니처가 어긋나면 CI가 실패합니다.

생성자는 안전한 기본값과 함께 구성 표면을 제공합니다:

매개변수	타입	기본값
`pageSize`	`PageSize`	`PageSize(595.276, 841.890, 'A4')`
`margins`	`Margin`	`Margin(10.0, 10.0, 10.0, 10.0)`
`compress`	`bool`	`true`
`autoPageBreak`	`bool`	`true`
`breakMargin`	`float`	`20.0`
`lang`	`string` (BCP-47)	`''`
`fontsDirectory`	`string`	`''`
`imageCacheBytes`	`int`	`52_428_800`
`deterministic`	`?DeterministicSettings`	`null`
`cryptoPolicy`	`?CryptoPolicyInterface`	`null`
`branding`	`?BrandingConfig`	`null`
`degradationPolicy`	`DegradationPolicy`	`Balanced`
`degradationOverrides`	`array<string, DegradationPolicy>`	`[]`
`cssRenderingMode`	`CssRenderingMode`	`Normal`
`auditCollector`	`?AuditCollector`	`null`
`cssFeatureFlags`	`?CssFeatureFlags`	`null`
`cssLayoutMode`	`CssLayoutMode`	`Streaming`
`retainedNodeBudget`	`int`	`50_000`
`layoutTelemetryCollector`	`?LayoutTelemetryCollector`	`null`
`telemetryEnabled`	`bool`	`false`
`outputColorProfile`	`OutputColorProfile`	`DeviceRGB`

세 가지 설정에 값 범위 제한이 있습니다. retainedNodeBudget는 닫힌 범위 [5_000, 100_000]을 허용합니다 (상수 RETAINED_NODE_BUDGET_MIN, RETAINED_NODE_BUDGET_MAX, 기본값 RETAINED_NODE_BUDGET_DEFAULT). withRetainedNodeBudget()는 해당 범위를 벗어나면 InvalidArgumentException을 던집니다. effectiveRetainedNodeBudget()는 스트리밍 모드에서 0을 반환합니다. 그 외의 경우에는 직접적인 위치 인수 생성에 대한 심층 방어 검사로 값을 범위 안으로 다시 클램프합니다. validate()는 개별 필드 wither가 단독으로는 볼 수 없는 교차 필드 불변식을 적용합니다. CssLayoutMode::Auto는 예약되어 있으며 NotImplementedException을 발생시킵니다. CssRenderingMode::Safe를 CssLayoutMode::Retained와 함께 사용하면 IncompatibleRenderingModeException을 발생시킵니다. auditCollector는 호출자가 제공하는 감사 보고서 수집기입니다. 이는 cssRenderingMode가 CssRenderingMode::Audit일 때만 소비되며, 이 경우 비공개 nextpdfAudit XMP 블록을 구동합니다. 다른 렌더링 모드에서는 무시됩니다.

NextPdfConfig는 별개의 관심사입니다. 이는 프로세스 전역 CSS 파서 한도를 보유하는, 인스턴스화할 수 없는 정적 유틸리티입니다. 이 한도는 최대 스타일시트 바이트 수(기본값 512 KB)와 최대 CSS 중첩 깊이(기본값 8)입니다. 이는 적대적 입력으로 인한 리소스 고갈에 대비한 보안 경계이며, 문서별 환경설정이 아닙니다. 따라서 이 한도들은 정적입니다. 세터는 하한값을 기준으로 클램프합니다 (max(1024, …) 바이트, max(1, …) 깊이). resetDefaults()는 테스트 전용으로 @internal로 표시됩니다.

API 표면

심볼	종류	주요 멤버
`NextPDF\Core\Config`	final readonly 클래스	생성자 매개변수 21개; 타입 지정 wither 19개; `validate()`, `isSafeMode()`, `isRetainedMode()`, `effectiveRetainedNodeBudget()`, `resolveFeatureFlags()`
`NextPDF\Core\Config::RETAINED_NODE_BUDGET_MIN`	const int	`5_000`
`NextPDF\Core\Config::RETAINED_NODE_BUDGET_MAX`	const int	`100_000`
`NextPDF\Core\Config::RETAINED_NODE_BUDGET_DEFAULT`	const int	`50_000`
`NextPDF\Core\NextPdfConfig`	final 클래스	`setMaxCssBytes()`, `getMaxCssBytes()`, `setMaxCssNestingDepth()`, `getMaxCssNestingDepth()`, `resetDefaults()` (`@internal`)

Wither 메서드: withPageSize, withMargins, withCompress, withAutoPageBreak, withLang, withFontsDirectory, withImageCacheBytes, withDeterministic, withCryptoPolicy, withBranding, withDegradationPolicy, withDegradationOverride, withCssRenderingMode, withCssFeatureFlags, withCssLayoutMode, withRetainedNodeBudget, withLayoutTelemetryCollector, withTelemetryEnabled, withOutputColorProfile.

코드 예제 — 빠른 시작

기본값으로 구성을 만들고 두 가지 설정을 조정합니다.

<?php

declare(strict_types=1);

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

$config = (new Config())
    ->withPageSize(PageSize::Letter())
    ->withMargins(Margin::uniform(18.0));

// Each wither returns a new instance; the original is unchanged.

코드 예제 — 프로덕션

결정적이고 검증된 구성을 만들고, 신뢰할 수 없는 입력에 대비해 프로세스 전역 CSS 한도를 강화합니다.

<?php

declare(strict_types=1);

use NextPDF\Core\Config;
use NextPDF\Core\CssRenderingMode;
use NextPDF\Core\NextPdfConfig;
use NextPDF\ValueObjects\Margin;
use NextPDF\ValueObjects\PageSize;

$config = (new Config())
    ->withPageSize(PageSize::A4())
    ->withMargins(Margin::symmetric(vertical: 20.0, horizontal: 15.0))
    ->withCompress(true)
    ->withCssRenderingMode(CssRenderingMode::Safe);

// Reject mutually exclusive modes before generation starts.
$config->validate();

// Process-wide hardening for hostile stylesheet input.
NextPdfConfig::setMaxCssBytes(262_144);   // 256 KB
NextPdfConfig::setMaxCssNestingDepth(4);

엣지 케이스 및 주의사항

Config는 validate()를 호출하기 전까지는 교차 필드 규칙이 적용되지 않습니다. wither는 단독으로 Safe + Retained 충돌을 감지할 수 없습니다. 생성 전에 validate()를 호출하세요.
withRetainedNodeBudget()는 자체 입력에 대해 예외를 던지는 유일한 wither입니다 (InvalidArgumentException, [5_000, 100_000] 범위 밖).
effectiveRetainedNodeBudget()는 스트리밍 모드에서 0을 반환하며, 이는 “Tier-1 예산이 적용되지 않음”을 나타내는 것이지 “노드가 허용되지 않음”이 아닙니다.
withLayoutTelemetryCollector()와 withTelemetryEnabled()는 서로 독립적입니다. 텔레메트리를 활성화하지 않고 수집기를 연결하면, 이후 카나리를 위해 단계적으로 준비됩니다. 수집기 없이 텔레메트리를 활성화하는 것은 유효하며 아무 동작도 수행하지 않습니다.
NextPdfConfig는 프로세스 전역이며 정적입니다. 변경 사항은 재설정될 때까지 프로세스 내 모든 문서에 영향을 미칩니다. 이는 문서별 환경설정이 아니라 보안 경계입니다. 요청별 변경 경로에서는 제외하세요.
NextPdfConfig::resetDefaults()는 @internal입니다. 프로덕션 코드에서 호출하지 마세요.

성능

wither는 새 Config 하나를 할당하고 기존 값 객체에 대한 참조를 복사합니다. 이는 설정 개수와 무관하게 O(1)이며, 보유한 모든 값 자체가 불변이므로 깊은 복사를 수행하지 않습니다. NextPdfConfig 접근자는 정적 필드 읽기이며 O(1)입니다. 이 참조 페이지의 기본 performance_budget는 wall_ms: 1500, peak_mb: 64입니다.

보안 참고사항

NextPdfConfig는 파서 리소스 사용을 제한하기 위해 존재합니다. 기본 512 KB 스타일시트 상한과 깊이 8 중첩 상한은 비정상적으로 크거나 깊게 중첩된 CSS로 인한 서비스 거부를 방지합니다. 스타일시트 소스를 신뢰할 수 없을 때는 두 한도를 모두 낮추세요. Config::cryptoPolicy는 암호화 정책 적용(예: FIPS 프로파일)을 위한 CryptoPolicyInterface를 담습니다. 기본적으로 null이며 withCryptoPolicy()를 통해 설정됩니다. Config::deterministic는 바이트 단위로 동일한 출력을 위한 고정 타임스탬프와 식별자를 제어하며, 재현 가능한 빌드에 필요합니다.

적합성

이 모듈은 엔진 구성이며 규범적 표준 인용을 포함하지 않습니다. 표준 동작을 구동하는 설정 — outputColorProfile (OutputIntent 방출), cryptoPolicy (FIPS), deterministic (재현 가능한 빌드) — 은 해당 동작을 방출하는 모듈에서 관련 절에 따라 문서화됩니다.