Support: 공용 유틸리티 + Clock + Sleeper

한눈에 보기

Support 모듈에는 엔진이 내부적으로 사용하는 교차 관심사 유틸리티가 포함되어 있습니다. 이와 함께 작은 공개 API 표면도 제공합니다. 여기에는 PSR-20 시스템 클록, 경고 수집 파이프라인, PDF 직렬화 기본 요소가 포함됩니다. 이 네임스페이스의 대부분은 내부 인프라입니다. 이 페이지에서는 외부 호출자가 의존할 수 있는 부분을 문서화하고, 내부 전용인 부분을 표시합니다.

설치

composer require nextpdf/core:^3

개념 개요

클록(PSR-20). SystemClock은 Psr\Clock\ClockInterface를 구현합니다. 이 클래스의 now()는 현재 시각을 DateTimeImmutable로 반환합니다. PSR-20 모델은 하나의 읽기 연산만 가진 클록 인터페이스를 정의하며, 이 연산은 현재 시각을 불변 날짜-시간 값으로 반환합니다(PSR-20 psr_20_clock#2.1). SystemClock이 기본값입니다. 클록이 주입되지 않으면 엔진은 이를 사용합니다. 테스트에서 고정된 시각이 필요하면 동일한 인터페이스를 구현하는 고정 클록을 대신 주입하세요. 바이트 단위로 동일한 출력을 얻으려면 클록을 Config::deterministic과 함께 사용하세요.

경고 파이프라인. WarningCollector는 치명적이지 않은 렌더링 문제를 전달하는 기본 인메모리 수단입니다. 엔진은 결정론적으로 발생하는 각 저하마다 Warning을 추가합니다. 예로 압축된 표 열, 해결되지 않은 글꼴, 누락된 글리프가 있습니다. 호출자는 생성 후 Document::getWarnings()를 통해 이를 읽습니다. Warning은 불변 값 객체입니다. 여기에는 WarningCode, WarningSeverity(warning 또는 degraded), 페이지, 요소 유형, 기능 ID, 저하-패리티 플래그, 메시지, DegradationImpact, 선택적 역량 ID가 담깁니다. WarningCode는 안정적인 식별자로 구성된 문자열 기반 enum입니다. 각 값에는 NEXTPDF_W_ 접두사가 붙습니다(예: NEXTPDF_W_FONT_UNRESOLVED). 이 접두사 덕분에 테스트에서 안전하게 매칭할 수 있습니다. addWithPolicy()는 활성 DegradationPolicy를 적용합니다. 엄격 정책에서는 규정 준수, 의미론, 차단 관련 영향이 DegradedException을 발생시킵니다. 균형 정책에서는 차단 영향만 예외를 발생시킵니다. 허용 정책은 예외를 발생시키지 않습니다.

PDF 기본 요소. PdfStringEscaper는 PDF 문자열 및 이름 이스케이프의 단일 기준입니다. escapeLiteral()는 PDF 리터럴 문자열에 필요한 문자(역솔리더스, 괄호, CR, LF, HT, BS, FF)를 이스케이프하고 NUL을 제거합니다. escapeName()는 이름 객체에서 인쇄 가능한 ASCII 및 PDF 구분 기호 집합을 벗어난 바이트를 16진수로 인코딩합니다. BinaryBuffer는 쓰기에 최적화된 바이너리 누적기입니다. PDF 객체와 스트림을 구성하는 데 사용됩니다. 대용량 문서에서는 스트리밍 모드가 php://temp 핸들로 데이터를 넘깁니다. 또한 서명 임베딩에 필요한 바이트 범위 연산도 지원합니다. PdfOperators는 콘텐츠 스트림 연산자 형식 문자열(경로, 텍스트, 그래픽 상태, 글꼴)을 담고 있습니다. 드로잉 계층과 파서 계층이 이를 공유합니다.

BinaryBuffer, PdfOperators 및 NextPDF\Support\의 나머지 대부분은 내부 인프라입니다. 라이터 계층과 드로잉 계층에서 이를 사용합니다. 이 항목들은 완전성과 감사를 위해 여기에 문서화되어 있습니다. 지원되는 공개 API 표면에는 포함되지 않습니다. 대신 Document 파사드와 Contracts 네임스페이스에 의존하세요. 공개 표면 멤버는 SystemClock, WarningCollector, Warning, WarningCode, WarningSeverity, DegradationImpact입니다.

API 표면

심볼	종류	가시성	주요 멤버
`NextPDF\Support\SystemClock`	final class	public	`now(): DateTimeImmutable` (PSR-20 `ClockInterface`)
`NextPDF\Support\WarningCollector`	final class	public	`add()`, `emit()`, `addWithPolicy()`, `getWarnings()`, `hasWarnings()`, `hasDegradedParity()`, `clear()`
`NextPDF\Support\Warning`	final readonly class	public	`$code`, `$severity`, `$page`, `$elementType`, `$featureId`, `$degradedParity`, `$message`, `$impact`, `$capabilityId`
`NextPDF\Support\WarningCode`	string enum	public	안정적인 `NEXTPDF_W_*` 식별자
`NextPDF\Support\WarningSeverity`	string enum	public	`Warning`, `Degraded`
`NextPDF\Support\DegradationImpact`	string enum	public	`Cosmetic`, `LayoutRisk`, `SemanticLoss`, `ComplianceRisk`, `Blocking`
`NextPDF\Support\PdfStringEscaper`	final readonly class	internal (내부)	`escapeLiteral()`, `escapeName()` (정적)
`NextPDF\Support\BinaryBuffer`	final class	internal (내부)	`write()`, `writeStream()`, `replaceAt()`, `extract()`, `enableStreaming()`, `getContents()`
`NextPDF\Support\PdfOperators`	final class	internal (내부)	콘텐츠 스트림 연산자 형식 문자열 상수

코드 샘플 — 빠른 시작

생성 후 수집된 경고를 읽는 예입니다.

<?php

declare(strict_types=1);

use NextPDF\Support\WarningCollector;

$collector = new WarningCollector();

// The engine appends warnings during rendering. After generation:
if ($collector->hasWarnings()) {
    foreach ($collector->getWarnings() as $warning) {
        \printf(
            "[%s] page %d: %s\n",
            $warning->code->value,
            $warning->page,
            $warning->message,
        );
    }
}

코드 샘플 — 프로덕션

결정론적 시각을 보장하도록 클록을 주입하고 저하-패리티 경고를 빌드 실패로 처리합니다.

<?php

declare(strict_types=1);

use NextPDF\Support\SystemClock;
use NextPDF\Support\WarningCollector;
use Psr\Clock\ClockInterface;

// Production uses the real system clock.
$clock = new SystemClock();
$now = $clock->now();          // DateTimeImmutable
$epoch = $now->getTimestamp(); // int

// In tests, swap in any ClockInterface that returns a fixed instant
// (the parameter is typed to the PSR-20 interface, not SystemClock).
function buildReport(ClockInterface $clock): \DateTimeImmutable
{
    return $clock->now();
}

$collector = new WarningCollector();
// ... run generation ...
if ($collector->hasDegradedParity()) {
    throw new \RuntimeException('Output parity degraded; failing the build.');
}

엣지 케이스 및 주의 사항

SystemClock::now()는 호출할 때마다 새로운 DateTimeImmutable을 반환합니다. 두 번의 호출이 같은 순간을 반환한다고 가정하지 마세요. 고정된 시각이 필요하면 고정 클록을 주입하세요.
WarningCollector는 인메모리 방식이며 인스턴스별로 동작합니다. 이것이 기본 채널입니다. JSON 사이드카와 CLI STDERR는 수집기 자체가 아니라 출력 경계에서 방출됩니다.
addWithPolicy()는 엄격 정책에서 렌더링 중에 DegradedException을 발생시킬 수 있습니다. 부분 출력을 원하면 생성 경계에서 이를 잡으세요.
WarningCode 값은 안정적인 문자열입니다. 사람이 읽을 수 있지만 변경될 수 있는 메시지 텍스트가 아니라 enum 케이스로 매칭하세요.
BinaryBuffer::getLength()는 스트림 인터페이스 동등성을 위해 의도적으로 제공되는 getOffset()의 별칭입니다. 둘 다 동일한 바이트 수를 반환합니다.
PdfStringEscaper, BinaryBuffer, PdfOperators는 내부용으로 취급하세요. 이 항목들은 공개 API 안정성 보장의 대상이 아닙니다.

성능

SystemClock::now()는 단일 객체 생성이므로 O(1)입니다. WarningCollector에 항목을 추가하는 작업은 상각 O(1) 리스트 푸시입니다. getWarnings()는 내부 리스트를 반환합니다. 스트리밍 모드의 BinaryBuffer는 디스크로 넘기기 전에 메모리를 maxmemory 임계값(기본값 2 MB)으로 제한하므로, 대용량 문서에서도 최대 메모리가 일정하게 유지됩니다. 이 참조 페이지의 기본 performance_budget은 wall_ms: 1500, peak_mb: 64입니다.

보안 참고 사항

클록 표면을 사용하면 Config::deterministic과 함께 고정 클록을 주입해 서명 및 타임스탬프가 찍힌 출력에서 벽시계로 인한 비결정성을 제거할 수 있습니다. PdfStringEscaper는 PDF 문자열 및 이름 출력을 위한 단일 감사 가능 이스케이퍼입니다. 모든 문자열 방출을 이를 통해 라우팅하면 사용자가 제공한 텍스트의 이스케이프되지 않은 괄호나 구분 기호로 인한 콘텐츠 주입을 방지할 수 있습니다. 경고에는 문서에서 파생된 세부 정보(요소 유형, 기능 ID)가 포함될 수 있습니다. 경고 출력을 신뢰 수준이 낮은 로그 싱크로 전달하기 전에 정제하세요.

적합성

사양	조항	주제
PSR-20 (PHP-FIG)	`psr_20_clock#2.1`	클록 읽기 연산이 불변 날짜-시간을 반환함
ISO 32000-2:2020	§7.3.4.2 / §7.3.5	리터럴 문자열 및 이름 객체 이스케이프(의역; ISO 본문 인용 없음, 청크 고정 없음)

SystemClock은 PSR-20 ClockInterface를 구현합니다. 이스케이퍼는 PDF 리터럴 문자열 및 이름 객체의 문자 규칙을 따릅니다. ISO 본문은 사이트 인용 정책에 따라 의역되었으며 원문 그대로의 청크는 고정되지 않았습니다.