Template — 심층 참조

한눈에 보기

이 심층 참조는 허용되는 JSON 템플릿 스키마, 모든 검증 규칙, 그리고 데이터 바인더의 정확한 타입별 포맷팅 동작을 문서화합니다. 이 모듈은 템플릿 정의를 파싱한 다음 호출자 데이터를 타입이 지정된 placeholder에 바인딩합니다. 포맷된 문자열을 방출하며, PDF 객체를 그리지는 않습니다.

가용성 및 라이선스

이 기능은 NextPDF Pro(nextpdf/pro)에 포함되며 Pro 등급 라이선스 엔벨로프로 활성화됩니다. 해당 자격이 없는 배포는 이 기능의 클래스를 로드하지 않습니다. 이 모듈을 게이팅하는 런타임 기능 플래그는 없습니다. 에디션 비교 및 라이선스 받기.

공개 API 표면

이 모듈은 두 개의 진입점 서비스와 네 개의 불변 값 객체를 노출합니다. 아래의 모든 심볼은 공개이며 안정적입니다.

심볼	매개변수	기본 동작	반환	던지거나 실패하는 조건	비고
TemplateParser::parse	string $json	검증한 다음 정의를 빌드	TemplateDefinition	검증 오류가 하나라도 있으면 InvalidArgumentException	먼저 validate에 위임합니다.
TemplateParser::validate	string $json	한 번의 패스로 모든 구조적 오류를 수집	list<string>(유효하면 빈 목록)	절대 던지지 않음. JSON 디코드 실패는 메시지로 반환	길이 및 정밀도 경계의 권위 있는 게이트.
TemplateDataBinder::bind	TemplateDefinition $template, array<string,mixed> $data	placeholder를 대소문자 구분 없이 매칭하고 타입별로 포맷	BindingResult	절대 던지지 않음. 이상은 경고 또는 누락 필드로 처리	키가 없으면 placeholder 기본값을 사용합니다.
TemplateDefinition::__construct	string $name, string $pageSize, string $orientation, list<TemplatePlaceholder> $placeholders, string $backgroundPdf = ''	파싱된 정의를 저장	TemplateDefinition	인수 타입 불일치 시 TypeError	Final readonly 값 객체.
TemplateDefinition::getPlaceholder	string $name	이름으로 대소문자 구분 없이 조회	TemplatePlaceholder|null	실패 없음. 없으면 null 반환	—
TemplateDefinition::requiredFields	없음	기본값이 없는 placeholder의 이름을 수집	list<string>	실패 없음	비어 있지 않은 기본값은 placeholder를 선택적으로 표시합니다.
TemplatePlaceholder::__construct	string $name, PlaceholderType $type, float $x, float $y, float $width, float $height, string $defaultValue = '', string $format = ''	하나의 placeholder 영역을 저장	TemplatePlaceholder	인수 타입 불일치 시 TypeError	좌표는 좌상단 기준 포인트 단위입니다.
TemplatePlaceholder::matches	string $key	대소문자 구분 없는 이름 비교	bool	실패 없음	—
BindingResult::__construct	list<BoundPlaceholder> $bindings, list<string> $missingFields, list<string> $warnings	바인딩 결과를 저장	BindingResult	인수 타입 불일치 시 TypeError	Final readonly 값 객체.
BindingResult::isComplete	없음	모든 필수 필드가 바인딩되었는지 보고	bool	실패 없음	missingFields가 비어 있으면 true.
BindingResult::count	없음	성공적으로 바인딩된 placeholder를 카운트	int	실패 없음	—
BoundPlaceholder::__construct	TemplatePlaceholder $placeholder, string $formattedValue, mixed $rawValue	placeholder를 포맷된 값과 짝지음	BoundPlaceholder	인수 타입 불일치 시 TypeError	Final readonly 값 객체.
PlaceholderType	enum 케이스 Text, Image, Barcode, Date, Number, Currency, Conditional	문자열 기반 placeholder 분류 체계	enum 인스턴스	알 수 없는 값에 대해 from()이 ValueError	tryFrom()은 대신 null을 반환합니다.
PlaceholderType::requiresFormatting	없음	해당 타입이 포맷 문자열을 소비하는지 보고	bool	실패 없음	Date, Number, Currency에 대해 true.

final class TemplateParser
{
    public function parse(string $json): TemplateDefinition;
    public function validate(string $json): array;
}

final class TemplateDataBinder
{
    public function bind(TemplateDefinition $template, array $data): BindingResult;
}

동작 계약

허용되는 JSON 형태:

{
  "name": "string (required, non-empty)",
  "pageSize": "A3|A4|A5|A6|B4|B5|Letter|Legal|Tabloid",
  "orientation": "P|L",
  "backgroundPdf": "optional path string",
  "placeholders": [
    { "name": "string", "type": "text|image|barcode|date|number|currency|conditional",
      "x": number, "y": number, "width": number, "height": number,
      "defaultValue": "optional", "format": "optional" }
  ]
}

검증 규칙은 모두 validate가 메시지로 표면화하며 parse가 하나의 예외로 집계합니다:

• 누락되거나 빈 name.
• 허용 목록에 없는 pageSize, 또는 P나 L이 아닌 orientation.
• 누락된 placeholders, 또는 배열이 아닌 값.
• placeholder별: 누락되거나 빈 이름, 잘못된 타입, 누락되거나 숫자가 아닌 x, y, width, height, 중복 이름(대소문자 구분 없음).
• defaultValue: 문자열이 아니거나, 4096바이트보다 길거나, ASCII 제어 문자를 포함.
• format: 문자열이 아니거나, 256바이트보다 길거나, ASCII 제어 문자를 포함.
• 음이 아닌 정수가 아니거나 30을 초과하는 number placeholder format.

바인딩 시맨틱(TemplateDataBinder::bind):

• 데이터 키는 placeholder 이름과의 대소문자 구분 없는 매칭을 위해 소문자로 변환됩니다.
• 비어 있지 않은 기본값이 있는 부재 키는 기본값을 바인딩하고, 기본값이 없는 부재 키는 missingFields에 보고됩니다.
• Text, image, barcode 값은 변경 없이 문자열로 캐스팅됩니다.
• Date 바인딩은 DateTimeInterface, 정수 Unix 타임스탬프, 또는 네 가지 명시적 형식 중 하나의 문자열을 허용합니다. 기본 출력 형식은 Y-m-d입니다.
• Number 바인딩은 number_format(value, decimals, '.', ',')을 사용합니다. 소수 자릿수는 format에서 오며, 기본값은 2이고, 0에서 30 범위로 제한됩니다.
• Currency 바인딩은 포맷된 숫자 앞에 format을 붙이며, 접두사는 기본적으로 $입니다.
• Conditional 바인딩은 불리언 캐스트에서 "true" 또는 "false"를 방출합니다.

엣지 케이스 및 실패 모드

• backgroundPdf는 이 모듈에 의해 결코 열리거나 역참조되지 않습니다. 렌더러에 전달되는 불투명한 문자열입니다.
• Number 또는 Currency placeholder에 바인딩된 숫자가 아닌 값은 경고를 생성하며, 값은 거부되지 않고 문자열로 캐스팅됩니다.
• Date 문자열은 엄격하게 파싱됩니다. 상대 및 자연어 토큰(“now”, “+1 year”, “tomorrow”)은 어떤 허용 형식과도 일치하지 않으므로 경고하고 원시 값이 변경 없이 그대로 통과합니다.
• 정수 date 값은 @ epoch 형식을 통해 Unix 타임스탬프로 읽힙니다.
• 바인더에 도달한 0에서 30 범위를 벗어난 Number format 정밀도는 경고와 함께 거부되며, 바인더는 기본 정밀도 2로 폴백합니다.
• 이 모듈에서는 암호 연산이 발생하지 않으므로 FIPS 모드 특정 동작이 없습니다.

적합성

직접적인 PDF 명세 표면은 존재하지 않습니다. 페이지 크기와 방향 어휘는 NextPDF 규약이며, 이 모듈은 PDF 객체가 아니라 포맷된 값을 방출합니다. 엄격한 문자열 date 허용 목록은 RFC 3339 §5.6에 정의된 ISO 8601의 인터넷 날짜/시간 프로파일과 더불어 Y-m-d 달력 날짜 및 두 가지 로컬 날짜-시간 형식을 허용합니다. NextPDF는 이러한 형식을 읽는 기능을 문서화하며, RFC 3339이나 ISO 8601에 대한 인증은 주장하지 않습니다.

개발 노트

• TemplateParser와 TemplateDataBinder는 상태를 갖지 않습니다. 단일 인스턴스는 재사용 가능하며 여러 바인딩에 걸쳐 안전하게 공유할 수 있습니다.
• 네 개의 값 객체는 final readonly입니다. 프로덕션 입력의 경우 직접 만들기보다 파서를 통해 구성하십시오.
• validate는 한 번의 패스로 모든 구조적 오류를 보고하는 반면, parse는 먼저 validate를 호출하고 집계된 메시지에 대해 던집니다. 폼 방식 피드백에는 validate를, fail-fast 수집에는 parse를 사용하십시오.
• 길이 및 정밀도 경계는 권위 있는 게이트로서 파서에서 강제됩니다. TemplateDataBinder는 number_format 메모리 증폭에 대한 싱크 측 방어로 숫자 정밀도를 다시 확인합니다.

게시 경계

이 페이지는 외부에서 관찰 가능한 동작과 지원되는 공개 API 표면만 문서화합니다. 내부 네임스페이스 경로, 헬퍼 클래스, 메커니즘 테이블, 런북 파일명, 티켓 접두사는 범위를 벗어납니다.

함께 보기

• Template (기능 가이드)
• Toc
• Merge