Branding — 심층 참조

한눈에 보기

이 페이지는 NextPDF\Enterprise\Branding 모듈의 심층 참조입니다. 이 모듈은 평가 출력을 표시하고 유료 출력은 그대로 둡니다. 라이선스로 해석된 BrandingMode가 전략을 선택하며, BrandingApplicator는 해석된 전략을 렌더링된 PDF 바이트에 적용합니다. 유료 라이선스 하에서 이 변환은 항등 변환입니다. 출력은 바이트 단위로 변경되지 않으며 코드 변경이 필요하지 않습니다. 평가 워크플로에 대해서는 먼저 Branding 기능 페이지를 읽으십시오.

가용성 및 라이선싱

이 기능은 NextPDF Enterprise(nextpdf/enterprise)에 포함되어 있으며 Enterprise 등급 라이선스 봉투로 활성화됩니다. 해당 자격이 없는 배포는 이 기능의 클래스를 로드하지 않습니다. 에디션 비교 및 라이선스 받기.

이 서브시스템은 모든 에디션 전반의 평가 동작을 관장하므로 전용 enterprise.branding 기능 코드를 지닙니다. 브랜딩 모드는 런타임에 서명된 라이선스 봉투로부터 해석되며, 어떤 애플리케이션 플래그도 이를 선택하지 않습니다. 유료 라이선스는 모드를 None으로 해석하며 절대 브랜딩된 출력을 생성하지 않습니다. 전환할 프로덕션 빌드가 없습니다.

공개 API 표면

심볼	매개변수	기본 동작	반환	예외 또는 실패	비고
BrandingMode	—	None ('none'): 수정 없음	—	—	문자열 기반 enum. EvaluationWatermark ('evaluation')는 평가 브랜딩을 활성화함.
BrandingStrategy	—	통합 지점이 소비하는 계약	—	—	인터페이스. 호출자는 BrandingMode에 직접 분기하지 않음.
BrandingStrategy::isActive	—	널 전략은 false, 평가 전략은 true	bool	—	false는 다른 모든 메서드가 항등 값을 반환함을 의미함.
BrandingStrategy::buildPageWatermark	float $pageWidth, float $pageHeight (포인트)	비활성 시 빈 문자열, 활성 시 대각선 워터마크 연산자	string	—	스트림은 페이지에 /helvetica 글꼴 리소스가 있다고 가정함.
BrandingStrategy::decorateProducer	string $producer	비활성 시 항등, 활성 시 평가 접미사 추가	string	—	기본 접미사: [EVALUATION].
BrandingStrategy::decorateSubject	string $subject	비활성 시 항등, 활성 시 평가 접두사를 앞에 붙임	string	—	빈 주제는 트리밍된 마커를 산출함.
BrandingStrategyFactory::create	BrandingMode $mode, ?EvaluationBrandingConfig $config = null	None을 NullBrandingStrategy에, EvaluationWatermark을 EvaluationBrandingStrategy에 매핑함	BrandingStrategy	—	정적. null 구성은 기본값을 사용함.
EvaluationBrandingConfig::__construct	6개의 선택적 명명 매개변수 (text, suffix, prefix, size, gray, angle)	기본값: 48 pt, 회색 0.85, 45도	인스턴스	빈 텍스트, 양수가 아닌 글꼴 크기, 또는 0.0–1.0 범위를 벗어난 회색에 대해 InvalidArgumentException	final readonly. 불변.
EvaluationBrandingStrategy	선택적 EvaluationBrandingConfig	워터마크 및 메타데이터 장식을 적용함	—	—	final readonly. BrandingStrategy를 구현함.
NullBrandingStrategy	—	모든 메서드에서 항등	—	—	유료 라이선스 하에서 선택됨.
BrandingApplicator::apply	string $pdfBytes, BrandingStrategy $strategy	비활성 전략: 입력을 바이트 단위로 반환. 활성: 증분 업데이트 하나를 추가함	string	활성 브랜딩을 안전하게 적용할 수 없을 때 BrandingApplicationException	순수하고 결정론적인 바이트 변환.
BrandingApplicationException	—	최종적, fail-closed 실패 신호	—	—	SPEC_CODE (SPEC-BRANDING-UNAPPLICABLE)를 지님. 팩토리 unsupportedStructure().

진입점 시그니처

enum BrandingMode: string
{
    case None = 'none';
    case EvaluationWatermark = 'evaluation';
}

public static function create(
    BrandingMode $mode,
    ?EvaluationBrandingConfig $config = null,
): BrandingStrategy

public function __construct(
    public string $watermarkText = 'EVALUATION COPY — Not for Production Use',
    public string $producerSuffix = ' [EVALUATION]',
    public string $subjectPrefix = '[EVALUATION] ',
    public float $watermarkFontSize = 48.0,
    public float $watermarkGray = 0.85,
    public float $watermarkAngle = 45.0,
)

public function apply(string $pdfBytes, BrandingStrategy $strategy): string

동작 계약

모드 및 전략 해석. 애플리케이션 코드가 아니라 라이선스 상태가 BrandingMode를 선택합니다. BrandingStrategyFactory::create는 None을 NullBrandingStrategy에, EvaluationWatermark을 EvaluationBrandingStrategy에 매핑합니다. 통합 지점은 BrandingStrategy 인터페이스를 소비하며 모드를 직접 검사하지 않으므로, 브랜딩 로직이 중앙 집중화된 상태로 유지됩니다. 유료 라이선스 하에서는 널 전략이 선택되며 출력은 브랜딩 서브시스템이 전혀 없이 생성된 출력과 동일합니다.

워터마크 생성. buildPageWatermark는 한 페이지에 대한 PDF 콘텐츠 스트림 연산자를 방출합니다. 격리된 그래픽 상태(q/Q), /helvetica 리소스 이름을 통한 standard-14 Helvetica 글꼴, 채우기 텍스트 렌더링 모드, 그리고 텍스트를 페이지 중심을 가로질러 대각선으로 배치하는 회전 행렬입니다. 기본 스타일은 회색 수준 0.85의 48 pt 텍스트를 45도 회전한 것입니다. 가운데 정렬은 글리프 수로 텍스트 너비를 근사합니다 — intl이 로드되면 자소 클러스터, 그렇지 않으면 mbstring을 통한 유니코드 코드 포인트, 최종 대체로는 바이트 길이입니다. 설계상 글리프별 전진 너비는 참조하지 않습니다. 워터마크 텍스트는 ISO 32000-2:2020 §7.3.4.2에 따라 PDF 리터럴 문자열로 이스케이프됩니다(백슬래시 및 괄호).

메타데이터 장식. decorateProducer는 /Producer 값에 생산자 접미사를 추가합니다. decorateSubject는 /Subject 값 앞에 주제 접두사를 붙입니다. 빈 주제는 트리밍된 마커를 산출하므로, 주제 메타데이터가 없는 문서도 여전히 표시됩니다.

바이트 적용. BrandingApplicator::apply는 브랜딩 제어의 최종 소비자입니다. 비활성 전략에서는 입력을 바이트 단위로 반환합니다. 활성 전략에서는 ISO 32000-2:2020 §7.5.6에 정의된 형태로 단일 증분 업데이트를 추가합니다. 원본 바이트는 그대로 유지되며, 추가된 본문은 장식된 Info 객체(기존 객체 번호를 재사용), 페이지당 하나의 워터마크 콘텐츠 스트림과 하나의 업데이트된 페이지 객체, 그리고 /Prev가 이전 startxref를 다시 가리키는 새로운 상호 참조 스트림(/Type /XRef, /W [1 4 2])을 담습니다. 이 변환은 주어진 입력과 구성에 대해 순수하고 결정론적입니다.

Fail-closed 계약. 전략이 활성일 때 입력은 브랜딩 가능해야 합니다. %PDF- 헤더, /Encrypt 항목 없음, 객체 스트림(/ObjStm) 없음, 상호 참조 스트림 꼬리, 그리고 모든 페이지에서 해석 가능한 /helvetica 글꼴 리소스입니다. 어떤 위반이든 브랜딩되지 않은 바이트를 반환하는 대신 BrandingApplicationException을 발생시킵니다. 호출자는 이 예외를 최종적인 것으로 취급해야 하며 원본의 표시되지 않은 바이트를 커밋해서는 안 됩니다.

엣지 케이스 및 실패 모드

• 브랜딩된 출력은 라이선스 상태가 평가 방식임을 의미합니다. 이는 결함이 아니라 라이선스 상태를 반영합니다.
• 워터마크는 설계상 가운데 정렬되고 대각선입니다. 프로덕션 용도로 조정할 수 없으며, 유료 라이선스가 이를 완전히 제거합니다.
• EvaluationBrandingConfig는 빈 워터마크 텍스트, 양수가 아닌 글꼴 크기, 그리고 0.0–1.0 범위를 벗어난 회색 수준을 InvalidArgumentException으로 거부합니다.
• 생산자, 주제, 또는 워터마크 변경을 생성하지 않는 활성 전략은 유료처럼 보이는 바이트를 방출하는 대신 BrandingApplicationException으로 거부됩니다.
• 사용 가능한 /MediaBox가 없는 페이지(부재 또는 상속됨)는 ISO 216 A4 기본값인 595.276 × 841.890 포인트로 워터마크가 적용됩니다.
• 단일 참조 및 배열 형태의 /Contents가 모두 지원됩니다. 워터마크 참조는 맨 위에 그려지도록 마지막에 추가됩니다. /Contents가 없는 페이지는 하나를 받습니다.
• Info 문자열 값은 원래 표현으로 왕복합니다. 16진수 문자열(UTF-16BE)은 16진수로 유지되고, 리터럴 문자열은 리터럴로 유지됩니다. 부재하는 키는 추가되며, 값에 비 ASCII 문자가 포함되면 16진수로 인코딩됩니다.
• 암호화된 문서는 거부됩니다. /Encrypt 하의 문자열 객체를 다시 쓰려면 문서 암호화 키가 필요하기 때문입니다.
• 실패는 안정적인 코드 SPEC-BRANDING-UNAPPLICABLE(BrandingApplicationException::SPEC_CODE)을 지니므로, 소비 파이프라인이 브랜딩 불가능한 출력을 데드레터 처리하고 감사할 수 있습니다.
• 이 모듈은 어떤 암호화 작업도 수행하지 않습니다. 라이선스 봉투 서명 검증은 라이선싱 서브시스템에 속합니다. 라이선싱 심층 참조를 참조하십시오.

적합성

주장	표준	절
증분 업데이트는 변경 사항을 파일 끝에 추가하고 원본 콘텐츠는 그대로 둡니다.	ISO 32000-2	§7.5.6
업데이트의 상호 참조 섹션은 변경된 객체만 포함하며, 추가된 트레일러는 이전 상호 참조 섹션을 찾는 Prev 항목을 지닙니다.	ISO 32000-2	§7.5.6
리터럴 문자열은 괄호로 작성되며, 균형이 맞지 않는 괄호와 역슬래시는 이스케이프 처리가 필요합니다.	ISO 32000-2	§7.3.4.2

모든 절은 의역된 것이며, NextPDF는 규범 텍스트를 재현하지 않습니다. NextPDF는 어떤 인증 주장도 하지 않습니다. 애플리케이터는 인용된 ISO 32000-2 형태로 증분 업데이트를 작성하며, 이는 기능 진술입니다. 인증되거나 독립적으로 검증된 작성기가 아닙니다. 이 페이지는 런타임 동작만 설명합니다. 어떤 보증도, 자격이나 법적 효력에 대한 어떤 진술도 하지 않으며, 법률 자문을 구성하지 않습니다. 평가 또는 구독의 약관은 오로지 라이선스 계약에 의해 정의됩니다.

개발 참고 사항

• BrandingMode, BrandingStrategy, 두 전략, 그리고 구성은 @since 3.0.0을 지닙니다. BrandingApplicator와 BrandingApplicationException은 @since 3.1.0을 지닙니다.
• 이 서브시스템은 어떤 네트워크 호출도 하지 않습니다. 애플리케이터는 자신이 다시 쓰는 구조적 필드, 즉 Info 딕셔너리 문자열, 페이지 딕셔너리, 그리고 상호 참조 꼬리만 읽습니다.
• 라이선스 봉투는 런타임이 발행자 서명을 검증하는 서명된 아티팩트입니다. 라이선스 프로비저닝, 갱신, 그리고 보안 저장은 운영자의 책임입니다.
• 모든 구체 타입은 final이며, 전략과 구성은 readonly이기도 합니다. 워터마크 스타일을 변경하려면 새 구성 인스턴스를 생성하십시오.
• BrandingStrategy::isActive()가 false를 반환하면 다른 모든 메서드에서 항등 값이 보장됩니다. 호출자는 성능을 위해 이에 대해 단락 평가할 수 있습니다.
• 워터마크 스트림은 /helvetica 리소스 이름을 참조합니다. Core는 자체 브랜딩을 위해 이 리소스를 등록합니다. Core 브랜딩을 비활성화하는 통합은 이 리소스가 존재하도록 보장해야 합니다.
• 애플리케이터는 어떤 다이제스트도 계산하지 않습니다. 호출자는 브랜딩된 바이트를 커밋하기 전에 다시 다이제스트합니다.
• 내부 메커니즘 세부 사항은 소스 저장소의 내부 문서에 남아 있으며 이 매뉴얼의 범위를 벗어납니다.

배포 경계

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

함께 보기

• Branding — 평가 브랜딩 서브시스템의 기능 페이지.
• Trial and Evaluation Branding — 종단 간 평가 스토리.
• Licensing — 심층 참조
• Enterprise 개요