core 및 일반 오류

범위

이 항목들은 NextPDF가 발생시키는 core 및 범용 예외를 다룹니다. 대부분은 기반 NextPdfException을 확장하며, 이는 그 자체로 \RuntimeException을 확장하고 ContextAwareExceptionInterface를 구현합니다. 그 인터페이스는 한 메서드 getContext(): array를 노출하며, 로그나 APM 페이로드로 직렬화하기에 안전한 프리미티브의 평면 snake_case 맵을 반환합니다.

NextPdfException 계열을 단일 catch (NextPdfException $e)로 잡으십시오. 이 집합에서 \RuntimeException을 직접 확장하는 몇몇 저수준 오류(아래 나열)를 포괄하기 위해 catch (\RuntimeException $e)도 추가하십시오. 기반 NextPdfException::getContext()는 빈 배열을 반환합니다. 서브클래스가 이를 재정의하여 도메인 필드를 추가합니다. 클래스가 getContext()를 재정의하지 않는 경우, 빈 배열을 상속하며 진단 세부 정보는 대신 메시지와 타입이 지정된 게터에 있습니다.

이 집합의 네 타입은 NextPdfException을 확장하지 않습니다. BlackPointCompensationUnsupportedException과 UnsupportedSourceDocumentException은 \RuntimeException을 직접 확장하며(이들은 \RuntimeException으로 잡으십시오), ComplianceViolation과 RuleViolation은 예외가 아니라 값 객체입니다. 이들은 엔진이 반환하는 오류 및 위반 데이터를 모델링하므로 여기에 문서화되어 있습니다.

기반 예외

NextPdfException

• 무엇인가. NextPDF core와 그 확장 패키지에 걸친 주요 NextPDF 예외 계열의 abstract 기반입니다. \RuntimeException을 확장하고 ContextAwareExceptionInterface를 구현합니다. 이 단일 타입을 잡으면 NextPdfException 계열을 가로챕니다. \RuntimeException을 직접 확장하는 몇몇 오류(위에 나열)는 \RuntimeException 잡기도 필요합니다.
• 컨텍스트. 기반 getContext()는 빈 배열을 반환합니다. 서브클래스가 이를 재정의하여 도메인별 필드를 반환합니다.
• 복구. 직접 발생하지 않습니다. 포괄 타입으로 사용하고, 특정 처리를 위해 구체 서브클래스로 분기하십시오.

구성 및 기능 게이팅

InvalidConfigException

• 발생 시점. Config 값 또는 값의 조합이 유효하지 않을 때입니다. 누락된 필수 설정, 상호 배타적 옵션, 또는 허용 범위를 벗어난 값입니다. 이는 개발자 오류를 나타냅니다. 호출 코드가 재시도 전에 바로잡아야 하는 구성을 공급했습니다. 메시지는 키, 예상 타입 또는 범위, 그리고 공급된 값의 실제 디버그 타입을 보고합니다.
• 컨텍스트. getContext()는 config_key, given_value, expected_type를 반환합니다. 타입이 지정된 게터: getConfigKey(), getGivenValue(), getExpectedType()입니다.
• 복구. 개발자 조치입니다. NextPDF를 다시 호출하기 전에 명명된 구성 키를 예상 타입 또는 범위의 값으로 수정하십시오.

NotImplementedException

• 발생 시점. 공개 API 진입점에 도달했지만 그 구현이 현재 릴리스에서 의도적으로 부재할 때입니다. bisect 이전 호출자에게 조용한 무동작 대신 시끄럽고 실행 가능한 실패를 주기 위해 존재하는 폐기된 심에 사용됩니다. 메시지는 기계 grep 가능한 feature 레이블과 followUp 참조(결함 ID, 추적 앵커, 또는 스프린트 이름)를 결합합니다.
• 컨텍스트. getContext()를 재정의하지 않으므로 빈 배열을 반환합니다. $feature와 $followUp 값은 public readonly 속성이며 메시지에 임베드됩니다.
• 복구. 라이브러리 호출자 조치입니다. 호출을 제거하거나, 명명된 후속 작업이 도입되는 향후 릴리스에 고정하십시오.

IncompatibleFeatureFlagsException

• 발생 시점. Config 빌드 시점(Config::validate())에 CssFeatureFlags 조합이 내부적으로 모순될 때입니다. 한 플래그가 비활성화된 다른 플래그를 전제로 합니다. 오늘날 유일하게 금지된 조합은 layoutSubgrid = true와 layoutGrid = false입니다. 서브그리드된 축은 부모 그리드 컨테이너에서 그리드 선을 도출하므로(CSS Grid Layout Module Level 2 §1), 그리드 없는 서브그리드는 존재할 수 없는 그리드를 기술합니다. 검사는 해석된 플래그에 대해 실행되므로, CssRenderingMode::Safe(모든 Phase 4+ 기능을 강제로 끔)는 이 조합을 발동시키는 대신 가립니다. StrictModeViolation을 확장합니다.
• 컨텍스트. getContext()는 부모 strict 모드 필드(cssDeviation, excId, chunkSha256, location)와 layoutGrid 및 layoutSubgrid 불리언을 병합합니다. location은 Config::validate()이며 cssDeviation은 플래그 쌍을 인코딩합니다.
• 복구. 라이브러리 호출자 조치입니다. layoutSubgrid와 함께 layoutGrid를 활성화하거나, layoutSubgrid를 비활성화하십시오.

IncompatibleRenderingModeException

• 발생 시점. Config 빌드 시점에 CssRenderingMode와 CssLayoutMode 짝이 모드 매트릭스의 호환 셀을 벗어날 때입니다. 오늘날 유일하게 금지된 짝은 CssRenderingMode::Safe + CssLayoutMode::Retained입니다. Safe는 모든 Phase 4+ 기능을 강제로 꺼서 유지 모드 서식 컨텍스트(Grid, Subgrid, @container)에 소비자가 없게 만들므로, 이 조합은 조용히 저하되도록 허용되는 대신 거부됩니다. StrictModeViolation을 확장합니다.
• 컨텍스트. getContext()는 부모 strict 모드 필드와 mode1(렌더링 모드 값), mode2(레이아웃 모드 값)를 병합합니다. cssDeviation은 모드 쌍을 인코딩하고, location은 Config::validate()입니다.
• 복구. 라이브러리 호출자 조치입니다. 롤백을 위해서는 Safe + Streaming을 선택하고, Grid / Subgrid / Container Queries를 위해서는 Retained와 함께 비-Safe 렌더링 모드(Normal / Strict / Audit)를 선택하십시오.

StrictModeViolation

• 발생 시점. CssRenderingMode::Strict 하에서 발생하는 모든 사양 이탈 예외의 abstract 기반입니다. strict 모드에서, 등록된 EXC-NNN 예외 항목과 연결되지 않은 감지된 CSS 이탈은 감지 지점에서 이 클래스(또는 서브클래스)의 인스턴스를 발생시킵니다. 직접 발생하지 않습니다. IncompatibleFeatureFlagsException과 IncompatibleRenderingModeException을 참조하십시오.
• 컨텍스트. getContext()는 네 가지 ADR-023 필드를 반환합니다. cssDeviation(이탈하는 구조의 짧은 레이블), excId(등록된 경우 레지스트리 식별자, 아니면 null), chunkSha256(알려진 경우 사양 인용 청크 해시, 아니면 null), location(호출자가 읽을 수 있는 기원, 아니면 null)입니다.
• 복구. 라이브러리 호출자 조치입니다. 이탈을 새로 승인된 EXC-NNN 항목으로 등록하거나, 렌더러를 수정하여 이탈을 제거하십시오.

HTML 및 CSS 입력

HtmlParsingException

• 발생 시점. HTML 입력 파싱 또는 DOM 구성이 실패할 때입니다. 잘못된 charset 선언, 입력 크기 한도 위반, 과도한 중첩 깊이, 요소 수 오버플로, 행 수 최댓값 같은 표 구조 오류입니다. CSS 전용 리소스 소진은 대신 CssParserLimitExceededException과 CssResolutionBudgetExceededException이 보고합니다.
• 컨텍스트. getContext()는 html_snippet(문제가 된 HTML의 짧게 잘린 발췌), position(바이트 오프셋, 알 수 없으면 -1), rule(위반된 파서 제약)을 반환합니다. 타입이 지정된 게터: getHtmlSnippet(), getPosition(), getRule()입니다.
• 복구. 개발자 조치입니다. HTML 입력을 단순화하거나 파서 한도를 조정하십시오.

CssParserLimitExceededException

• 발생 시점. CSS 입력이 구성된 파서 안전 한도를 초과할 때입니다. 이름 있는 생성자를 통해 두 범주가 다뤄집니다. forByteLimit()(안전한 정규식 처리에 비해 스타일시트가 너무 큼)과 forNestingDepth()(CSS 중첩 재귀가 너무 깊음)입니다. 두 메시지 모두 실제 값과 한도를 명시합니다.
• 컨텍스트. getContext()는 limit_type(byte 또는 nesting_depth), actual, limit을 반환합니다.
• 복구. 개발자 조치입니다. 스타일시트를 더 작은 시트로 분할하거나, 중첩 깊이를 줄이거나, 구성된 한도를 높이십시오.

CssResolutionBudgetExceededException

• 발생 시점. CSS :has() 해석이 순회 예산을 초과할 때입니다. 2-패스 :has() 리졸버는 병적인 선택자가 2차 문서 순회를 일으키는 것을 막기 위해 엄격한 노드 방문 예산을 강제합니다. 총 방문 횟수가 한도를 초과하면 스타일시트가 너무 복잡한 것으로 거부됩니다. 메시지는 방문 횟수와 예산을 명시합니다.
• 컨텍스트. getContext()는 visits와 budget을 반환합니다. 타입이 지정된 게터: getVisits(), getBudget()입니다.
• 복구. 개발자 조치입니다. 선택자 복잡도를 줄이거나, 구성된 예산을 높이십시오.

폰트 및 이미지

FontNotFoundException

• 발생 시점. 파일 시스템 수준에서 폰트 파일을 찾거나 읽을 수 없을 때입니다. 요청된 패밀리나 경로가 존재하지 않거나, 읽을 수 없거나, 구성된 폰트 디렉터리에 접근할 수 없습니다. 폰트 데이터 자체는 유효할 수 있습니다. 이는 단지 도달할 수 없음을 나타냅니다. 메시지는 탐색한 경로를 나열합니다.
• 컨텍스트. getContext()는 font_name, search_paths(목록), fallback_attempted(불리언)를 반환합니다. 타입이 지정된 게터: getFontName(), getSearchPaths(), wasFallbackAttempted()입니다.
• 복구. 개발자 조치: 폰트 경로를 확인하십시오. 인프라 조치: 폰트 파일이나 디렉터리의 파일 권한을 수정하십시오.

FontParsingException

• 발생 시점. 폰트 파일을 찾았지만 그 내용을 사용할 수 없을 때입니다. 손상되었거나, 지원되지 않는 형식이거나, 필수 테이블이 누락되었습니다. TrueType, Type 1, CFF, OpenType 파싱 중의 구조 검증 실패를 다룹니다. 잘린 헤더, 잘못된 테이블 디렉터리, 누락된 필수 테이블(head, hhea, OS/2), 언패킹 오류, 크기 위반입니다. 메시지는 파일과 파싱 오류를 명시합니다.
• 컨텍스트. getContext()는 font_file과 parse_error를 반환합니다. 타입이 지정된 게터: getFontFile(), getParseError()입니다.
• 복구. 개발자 조치입니다. 폰트 파일을 유효한 것으로 교체하십시오.

ImageProcessingException

• 발생 시점. 이미지를 디코딩할 수 없거나, 지원되지 않는 형식이거나, GD/Imagick 처리에 실패할 때입니다. 인식할 수 없는 매직 바이트, 손상된 JPEG 데이터, 지원되지 않는 MIME 타입, 파일 크기 한도 위반, GD 리소스 할당 실패입니다. 이미지에는 접근할 수 있었지만 임베딩을 위해 픽셀 데이터를 추출할 수 없었습니다.
• 컨텍스트. getContext()는 image_path(인라인 데이터의 경우 비어 있음), format(감지되었거나 예상됨, 예: jpeg, png, unknown), operation(예: decode, resize, embed)을 반환합니다. 타입이 지정된 게터: getImagePath(), getFormat(), getOperation()입니다.
• 복구. 개발자 조치입니다. 유효하고 지원되는 이미지 파일을 공급하십시오.

출력, 레이아웃, 직렬화

CompressionException

• 발생 시점. FlateDecode(zlib) 압축 또는 압축 해제가 실패할 때입니다. 콘텐츠 스트림, 폰트 데이터, 페이지 콘텐츠, 첨부 데이터, 교차 참조 스트림에 대한 gzcompress/gzuncompress 실패입니다. 일반적으로 손상된 입력 스트림, 불충분한 메모리, 또는 누락된 zlib 확장입니다.
• 컨텍스트. getContext()는 algorithm(필터 이름, 예: FlateDecode, LZWDecode)과 stream_length(바이트 길이, 알 수 없으면 -1)를 반환합니다. 타입이 지정된 게터: getAlgorithm(), getStreamLength()입니다.
• 복구. 인프라 조치입니다. ext-zlib가 로드되었고 메모리가 충분한지 확인하십시오.

WriterException

• 발생 시점. PDF 직렬화, 선형화, 또는 I/O 출력이 실패할 때입니다. PdfWriter 스트림 쓰기 오류, 교차 참조 테이블 손상, 헤더/트레일러 생성 실패, 객체 참조 해석 실패, 파일 쓰기 오류, 출력 버퍼 오버플로입니다. 유효한 메모리 내 문서를 유효한 바이트 스트림으로 직렬화할 수 없었습니다. 메시지는 단계를 명시합니다.
• 컨텍스트. getContext()는 output_path(문자열 출력의 경우 비어 있음)와 writer_state(단계, 예: header, body, xref, trailer)를 반환합니다. 타입이 지정된 게터: getOutputPath(), getWriterState()입니다.
• 복구. 인프라 조치입니다. 디스크 공간, 파일 권한, 출력 스트림을 확인하십시오.

PageLayoutException

• 발생 시점. 페이지 레이아웃 제약을 충족할 수 없을 때입니다. 칼럼 레이아웃 위반(불충분한 너비, 잘못된 칼럼 수), 페이지 경계를 넘는 콘텐츠 넘침, 여백 충돌입니다. 요청된 레이아웃이 주어진 페이지 치수와 콘텐츠에 대해 기하적으로 불가능합니다. 메시지는 알려진 경우 페이지 번호와 위반된 제약을 명시합니다.
• 컨텍스트. getContext()는 page_number(1 기반, 알 수 없으면 0)와 constraint를 반환합니다. 타입이 지정된 게터: getPageNumber(), getConstraint()입니다.
• 복구. 개발자 조치입니다. 페이지 크기, 여백, 칼럼 설정, 또는 콘텐츠를 조정하십시오.

TemplateException

• 발생 시점. TemplateManager에서 PDF 템플릿 임포트 또는 재사용 작업이 실패할 때입니다. 잘못된 템플릿 상태 전이(템플릿을 순서에 어긋나게 시작하거나 종료), 존재하지 않는 템플릿 참조, 템플릿 직렬화 중의 스트림 압축 실패입니다. 메시지는 작업과 할당된 경우 템플릿 id를 명시합니다.
• 컨텍스트. getContext()는 template_id(아직 할당되지 않은 경우 비어 있음)와 operation(예: begin, end, use, serialize)을 반환합니다. 타입이 지정된 게터: getTemplateId(), getOperation()입니다.
• 복구. 개발자 조치입니다. 템플릿 사용 순서나 소스 PDF를 수정하십시오.

콘텐츠 스트림 불변식

ContentStreamBalanceException

• 발생 시점. ContentStreamBuilder가 스트림 종료 시(또는 불변식을 즉시 단언할 때 스트림 도중) 불균형한 연산자 쌍을 감지할 때입니다. 균형 불변식에 실패한 깊이 카운터를 캡처하여, 어떤 에미터가 짝이 되는 Q, ET, EMC 없이 q, BT, BMC를 누출했는지 로깅이 식별할 수 있게 합니다. ISO 32000-2:2020 §8.4.2(그래픽 상태 스택), §9.4.1(텍스트 객체), §14.6(마크 콘텐츠)에 따릅니다.
• 컨텍스트. getContext()는 graphics_depth, text_block_depth, marked_content_depth, offending_operator를 반환합니다. 타입이 지정된 게터: getGraphicsDepth(), getTextBlockDepth(), getMarkedContentDepth(), getOffendingOperator()입니다.
• 복구. 개발자 조치입니다. 구조를 열고 닫지 않은 에미터를 찾으십시오.

GraphicsStateBalanceException

• 발생 시점. PDF 콘텐츠 스트림이 불균형한 q/Q 연산자로 종료될 때입니다. ISO 32000-2:2020 §8.4.2은 각 그래픽 상태 저장(q)이 스트림 종료 전에 정확히 하나의 복원(Q)과 짝지어질 것을 요구합니다. 불균형은 변환, 클리핑 경로, 색, 렌더링 의도를 후속 페이지나 Form XObject로 누출합니다. 엄격한 그래픽 상태 검사가 활성화된 경우(NEXTPDF_GFXSTATE_STRICT=1)에만 발생합니다. 완화 모드에서는 대신 trigger_error()를 통해 경고가 방출됩니다.
• 컨텍스트. getContext()는 save_depth(저장이 너무 많으면 양수, 복원이 너무 많으면 음수)를 반환합니다. 타입이 지정된 게터: getSaveDepth()입니다.
• 복구. 개발자 조치입니다. 짝이 맞지 않는 save()/restore() 쌍을 찾으십시오.

MissingShadingResourceException

• 발생 시점. Shading 리소스 레지스트리 컨텍스트 없이 ConicGradientRenderer::render()가 호출될 때입니다. v10.0.0 호환성 파괴 변경은 이전의 암시적 마커 맵 대리 경로를 제거했습니다. 호출자는 /ShadingType 4 간접 객체가 페이지의 Shading 리소스 하위 사전에 대해 등록되도록 ShadingResourceRegistryInterface로 렌더러를 구성해야 합니다(ISO 32000-2 §8.7.4.2 / §8.7.4.3). 메시지는 호출자 컨텍스트를 명시하고 v9.x→v10.0 마이그레이션 노트를 가리킵니다.
• 컨텍스트. getContext()는 context(짧은 호출자 컨텍스트 레이블, 예: ConicGradientRenderer::render)를 반환합니다.
• 복구. 라이브러리 호출자 조치입니다. render()를 호출하기 전에 렌더러 생성자에 Shading 리소스 레지스트리 인스턴스를 연결하십시오.

선형화 (Fast Web View)

LinearizationInvariantException

• 발생 시점. v2 3-패스 Linearizer가 MEASURE → PLACE → FILL 단언이 위반되었음을 감지할 때입니다. Pass 1이 예측한 파일 길이와 일치하지 않는 Pass 3 바이트 수(오프셋 드리프트), 직렬화된 너비에 비해 너무 작은 선형화 사전 자리표시자, 또는 최종 출력과 일치하지 않는 /H [offset length] 힌트 스트림 오프셋입니다. 손상된 PDF를 방출하는 대신 이를 표면화하는 것은 명시된 안전성 보장입니다.
• 컨텍스트. getContext()는 invariant(위반된 불변식 이름), expected, actual, delta(부호 있는 차이)를 반환합니다. 타입이 지정된 게터: getInvariant(), getExpectedValue(), getActualValue()입니다.
• 복구. 유지보수자 조치입니다. 버그 보고를 제출하십시오. 이 불변식은 모든 올바른 형식의 입력에 대해 성립해야 합니다. 연결된 이전 예외를 캡처하십시오.

LinearizationUnimplementedException

• 발생 시점. 선형화기 기능 플래그가 의도적으로 비활성화된 백엔드로 설정되었을 때입니다. 현재 linearizerVersion === 'v1-noop'에 대해서만 발생합니다. 이는 코드 변경이나 재배포 없이 런타임에 모든 선형화 시도를 거부하는 비상 다운그레이드 설정으로, 프로덕션에서 Fast Web View를 킬 스위치로 끄는 데 유용합니다.
• 컨텍스트. getContext()는 reason(짧고 사람이 읽을 수 있는 설명)을 반환합니다. 타입이 지정된 게터: getReason()입니다.
• 복구. 운영자 / 릴리스 엔지니어링 조치입니다. 구성을 조정하거나 수정된 백엔드 버전으로 업그레이드하십시오.

적합성 및 프로파일 불변식

ConformanceViolationException

• 발생 시점. 요청된 기능을 문서의 선언된 ISO 적합성 계약을 깨지 않고는 방출할 수 없고, 엔진이 비적합 객체를 쓰는 대신 fail-closed될 때입니다. 표준 트리거는 PDF/A 보관 프로파일 하의 멀티미디어 Screen 주석 또는 Rendition 동작(ISO 32000-2:2020 §12.5.6.18 / §13.2)으로, 모든 PDF/A 부분이 이를 금지합니다(ISO 19005 시리즈). 파일이 veraPDF 검증에 실패할 것이므로, 엔진은 사전에 거부합니다.
• 컨텍스트. getContext()는 conformance_mode(선언된 모드, 예: pdfa4)와 feature(거부된 기능, 예: Screen annotation)를 반환합니다. 둘 다 public readonly 속성입니다. 이유는 예외 메시지입니다.
• 복구. 개발자 조치입니다. 보관용 출력의 경우 멀티미디어 호출을 빼거나, 비보관 적합성 프로파일을 대상으로 하십시오(기본값 ConformanceMode::Plain).

PdfRViolationException

• 발생 시점. PDF/R-1(ISO 23504-1:2020) 적합성 불변식이 위반될 때입니다. 값 객체 구성 시점(PdfRStrip, PdfRPage, PdfRDocument 프로파일) 또는 검증자 시점(PdfRValidator)입니다. 감사 소비자가 자유 텍스트를 파싱하지 않고 발견 사항을 올바른 §6 하위 절로 라우팅할 수 있도록, 문제가 된 규범 절과 한 줄 위반 설명을 캡처합니다.
• 컨텍스트. getContext()는 standard(항상 ISO 23504-1:2020), clause(절 경로, 예: 6.6.1), violation을 반환합니다. 타입이 지정된 게터: getClause(), getViolation()입니다.
• 복구. 개발자 조치입니다. 거부된 입력을 바로잡거나, 인용된 절에 적합하도록 문서를 다시 빌드하십시오.

바코드 생성

BarcodeException

• 발생 시점. 지원되는 모든 심볼로지(Code 39/128, UPC-A/E, EAN-8/13, Interleaved/Standard 2-of-5, POSTNET, PLANET, MSI, ISBN, ISSN, QR Code, PDF417, DataMatrix, JabCode)에 걸쳐 잘못된 데이터나 인코딩 오류로 바코드 생성이 실패할 때, 그리고 이미지 생성 중 GD 렌더링 실패가 있을 때입니다. 바코드 값은 메시지와 컨텍스트에서 128바이트로 발췌 제한됩니다. 지나치게 길거나 바이너리인 페이로드는 ... (<N> bytes, truncated) 표시와 함께 잘려 저장되므로 로그에 통째로 복사될 수 없습니다.
• 컨텍스트. getContext()는 barcode_type(심볼로지, 예: QRCODE, EAN13, CODE128)과 value(잘린 값)를 반환합니다. 타입이 지정된 게터: getBarcodeType(), getValue()입니다.
• 복구. 개발자 조치입니다. 바코드 데이터나 심볼로지 선택을 바로잡으십시오.

BarcodeEncoderNotFoundException

• 발생 시점. 요청된 인코더 타입이 알 수 없거나 그 기능 게이트가 닫혀 있을 때 BarcodeEncoderRegistry에서 발생합니다. 또한 PSR-11 Psr\Container\NotFoundExceptionInterface를 구현하므로 레지스트리가 표준을 준수하는 컨테이너입니다. 메시지는 심볼로지와 이유를 명시합니다.
• 컨텍스트. getContext()를 재정의하지 않으므로 빈 배열을 반환합니다. type과 reason은 getType()과 getReason() 게터를 통해, 그리고 메시지에서 사용할 수 있습니다.
• 복구. 개발자 조치입니다. 인코더를 등록하거나, 그것을 제공하는 패키지를 설치하십시오(예: Micro QR / DotCode / HanXin / JabCode의 경우 nextpdf/pro).

암호화, 암호, 서명

EncryptionException

• 발생 시점. PDF 암호화 또는 복호화가 실패할 때입니다. AES-256-CBC 암호화/복호화 실패, OpenSSL 오류, 잘못된 IV 크기, 해시 계산 실패, UE/OE 값 계산 오류입니다. 일반적으로 누락되었거나 잘못 구성된 OpenSSL 확장, 잘못된 키 자료, 또는 손상된 암호화 데이터입니다. 메시지는 작업과 알고리즘을 명시합니다.
• 컨텍스트. getContext()는 algorithm(예: AES-256-CBC)과 operation(예: encrypt, decrypt, key_derivation)을 반환합니다. 타입이 지정된 게터: getAlgorithm(), getOperation()입니다.
• 복구. 인프라 조치입니다. OpenSSL이 사용 가능하고 올바르게 구성되었는지 확인하십시오. 암호화 및 권한을 참조하십시오.

UnsupportedAlgorithmException

• 발생 시점. 현재 런타임에서 암호 알고리즘을 실행할 수 없을 때입니다. 필수 PHP 확장을 사용할 수 없거나, 기저 라이브러리에 프리미티브가 없거나, 번들된 hash 확장이 SHAKE/XOF 변형을 합성할 수 없거나, 알고리즘이 SignatureAlgorithmRegistry에 등록되지 않았습니다. 엔진은 더 약한 프리미티브로 조용히 저하해서는 안 되므로 대신 이를 표면화합니다. 정적 팩터리 nonFipsHostUnderFipsProfile()은 RegulatoryProfile::FIPS가 선택되었지만 FIPS 검증 OpenSSL 제공자를 확인할 수 없을 때(FIPS_ABSENT와 INDETERMINATE 모두 fail-closed) 이를(알고리즘 식별자 regulatory-profile:fips로) 발생시킵니다.
• 컨텍스트. getContext()는 algorithm(이름 또는 OID, 예: shake256, Ed25519, AES-256-GCM)과 reason(운영자가 조치 가능)을 반환합니다. 타입이 지정된 게터: getAlgorithm(), getReason()입니다.
• 복구. 운영자 조치: 누락된 확장을 설치하거나 런타임을 업그레이드하십시오. FIPS 게이트의 경우, FIPS 검증 OpenSSL 빌드를 설치하거나 NEXTPDF_FIPS_MODE를 명시적으로 설정하십시오. 개발자 조치: SignatureAlgorithmRegistry::register()를 통해 맞춤 알고리즘 디스크립터를 등록하십시오.

SignatureException

• 발생 시점. 디지털 서명 작업이 실패할 때입니다. 인증서 및 개인 키 처리(PKCS#12 파싱, PEM/DER 디코딩, X.509 검증), PKCS#7/CMS 구성, ECDSA 서명 형식, 컨테이너 크기 위반, DER 인코딩, PAdES 오케스트레이션입니다. TSA 전용 오류는 대신 더 구체적인 TsaException이 보고합니다. 위치 인자 생성자보다 타입이 지정된 이름 있는 팩터리를 선호하십시오. 각각은 근본 원인을 메시지 끝에 결합합니다. 예: ltvCapabilityMissing()(B-LT/B-LTA에는 nextpdf/enterprise 필요), tsaRequired() / tsaUrlEmpty() / tsaEmptyToken(), httpClientMissing(), hsmSignerMissing() / hsmSignatureEmpty(), signatureContentsNotFound() / signatureContentsPaddingCorrupt(), unexpectedKeyType(), pemDecodingFailed(), Ed25519 계열(ed25519SignatureMalformed(), ed25519RoundTripVerifyFailed(), ed25519KeyParseFailed(), ed25519SeedInvalid(), ed25519SecretKeyMalformed(), ed25519PublicKeyInvalid()), documentTimestampNotEmitted(), algorithmPolicyRejected(), digestOnlyAlgorithmRefused(), encryptedLtvUnsupported(), incrementalUpdateWriterMissing(), 그리고 OCSP 상태 쌍 nonSuccessfulOcspResponseStatus() / reservedOcspResponseStatus()(RFC 6960 §4.2.1)입니다. 이 팩터리들은 조용히 레벨을 낮춘 서명을 방출하는 대신 fail-closed됩니다.
• 컨텍스트. getContext()는 cert_info(주체 DN 또는 지문, 또는 비어 있음), signature_level(시도된 PAdES 레벨, 예: B-B, B-T, B-LT, B-LTA), detail(조치 가능한 진단, 레거시 위치 인자 생성자의 경우 비어 있음)을 반환합니다. 타입이 지정된 게터: getCertInfo(), getSignatureLevel(), getDetail()입니다.
• 복구. 개발자 조치: 인증서/키 구성을 수정하십시오. 기능 누락 팩터리의 경우, 명명된 패키지를 설치하십시오. 팩터리별 증상 및 해결 항목은 서명 및 타임스탬프 실패를 참조하십시오.

BlackPointCompensationUnsupportedException

• 발생 시점. 호출자가 null 어댑터에 비-Default ISO 18619 흑점 보정 변환을 적용하라고 요청할 때 NullBlackPointCompensationTransform::transform()에서 발생합니다. null 어댑터는 색 관리 백엔드가 없는 환경을 위한 안전한 폴백입니다. 실제 색 관리 모듈 없이 변환된 샘플을 생성하면 변환을 조용히 잘못 보고하게 됩니다. 여기 있는 대부분의 항목과 달리, 이는 NextPdfException이 아니라 \RuntimeException을 직접 확장하므로 기존 catch (\RuntimeException) 경로가 계속 작동합니다.
• 컨텍스트. getContext() 없음. 평범한 \RuntimeException입니다. 세부 정보는 메시지에 있습니다.
• 복구. 개발자 조치입니다. 실제 BlackPointCompensationTransform(LittleCMS, Argyll, 순수 PHP)을 등록하거나, /UseBlackPtComp를 BlackPointCompensation::Default로 제한하십시오.

문서 조립 및 접근성

UnsupportedSourceDocumentException

• 발생 시점. 소스 문서를 병합/분할 출력으로 안전하게 복사할 수 없고, 작업이 손상되었거나 보안이 손상된 결과를 방출하는 대신 fail-closed될 때입니다. 이름 있는 팩터리를 사용하십시오. encrypted()(ISO 32000-2 §7.6 — 키 없이는 콘텐츠를 복사할 수 없음), signed()(§12.8 — 페이지를 복사하면 서명 바이트 범위가 무효화됨), unsupportedStreamFilter()(객체 그래프 리더가 왕복할 수 없는 필터), multipleInteractiveForms()(문서화된 제한: 둘 이상의 소스가 비어 있지 않은 /AcroForm을 가짐, §12.7), splitWithInteractiveForm()(문서화된 제한: 폼을 가진 소스의 페이지 부분집합을 만들면 위젯이 고아가 됨)입니다. NextPdfException이 아니라 \RuntimeException을 직접 확장합니다.
• 컨텍스트. getContext() 없음. 평범한 \RuntimeException입니다. 원인과 영향받은 객체 번호가 메시지에 명시됩니다.
• 복구. 개발자 조치입니다. 소스를 먼저 복호화하거나 키를 공급하십시오. 서명된 소스의 경우, 대신 병합 후 서명하십시오. 다중 폼 병합의 경우, 하나를 제외한 모든 소스의 폼 필드를 평탄화하거나 제거하십시오. 폼을 가진 분할의 경우, 분할 전에 폼을 평탄화하십시오.

InvalidBcp47TagException

• 발생 시점. 후보 언어 태그가 RFC 5646 §2.1 ABNF에서 잘못된 형식이거나 큐레이션된 레지스트리 조회에 실패할 때 Bcp47Validator::validate()에서 발생합니다. BCP-47 / ISO 14289-2:2024 §8.4.4에 도메인 특화되어 있으며, 접근성 이음새 다운스트림의 호출자가 좁은 타입을 잡을 수 있도록 InvalidConfigException과 구별됩니다. 술어 쌍 Bcp47Validator::isWellFormed() / isValid()는 예외보다 분기를 선호하는 호출자를 위한 하위 호환 반환 값 표면으로 남아 있습니다.
• 컨텍스트. getContext()는 tag(공급된 그대로의 후보)와 reason(안정적인 기계 판독 가능 거부 코드, 예: empty-string, well-formed-shape, unregistered-primary, duplicate-variant)을 반환합니다. 타입이 지정된 게터: getTag(), getReason()입니다.
• 복구. 개발자 조치입니다. 언어 태그를 올바른 형식의 등록된 BCP-47 태그로 바로잡으십시오. 폰트 및 태깅을 참조하십시오.

FormFieldAccessibilityException

• 발생 시점. 엄격한 접근 가능 필드 이름 강제가 활성화된 상태로 PDF/UA 문서를 생성하는 동안, 대화형 폼 필드가 합성된(작성자가 공급하지 않은) 접근 가능 이름에 의존하게 될 때입니다. 기본 PDF/UA 출력은 필드가 절대 이름 없이 남지 않도록 위젯 /Contents에 합성 폴백 이름을 방출합니다. strict 모드는 대신 화면 읽기 프로그램 사용자가 실제 설명을 얻도록 작성자가 의미 있는 이름(툴팁, 또는 동작 없는 누름 버튼의 캡션)을 공급할 것을 요구합니다(ISO 14289-2:2024 §8.10.2).
• 컨텍스트. getContext()를 재정의하지 않으므로 빈 배열을 반환합니다. $fieldId는 public readonly 속성입니다. 이유는 메시지입니다.
• 복구. 개발자 조치입니다. 엄격한 PDF/UA 문서를 생성하기 전에 명명된 필드에 툴팁 / 접근 가능 이름을 공급하거나, strict 모드를 비활성화하십시오. PDF/A 및 PDF/UA 검증을 참조하십시오.

VendorExtensionRegistryConflictException

• 발생 시점. 호출자가 이미 등록된 메타데이터와 일치하지 않는 설명으로 알려진 PDF 개발자 확장 벤더 접두사(ISO 32000-2:2020 §7.12.1)를 재등록할 때 VendorExtensionRegistry::register()에서 발생합니다. 디스크립터는 추가 전용이며 충돌이 감지됩니다. 이 타입이 지정된 예외는 호출자가 이 특정 클래스를 잡을 수 있도록 일반 \RuntimeException을 대체했습니다.
• 컨텍스트. getContext()는 prefix, existing_description, attempted_description을 반환합니다. 타입이 지정된 게터: getPrefix(), getExistingDescription(), getAttemptedDescription()입니다.
• 복구. 개발자 조치입니다. 기존 설명으로 접두사를 등록하거나, 구별되는 접두사를 사용하십시오. 등록된 메타데이터를 덮어쓰지 마십시오.

감사 내보내기

AuditExportException

• 발생 시점. 감사 내보내기 번들 조립, 추적성 매트릭스 생성, 또는 스키마 투영이 런타임에 실패할 때입니다. claims.json / manifest.json에 대한 I/O, 표준 번들의 JSON 인코딩/디코딩, AuditExporter::projectToV1() 하위 호환 경로의 스키마 버전 불일치를 다룹니다. 메시지는 단계, 알려진 경우 아티팩트, 그리고 세부 정보를 명시합니다.
• 컨텍스트. getContext()는 stage(예: read_claims, encode_bundle, project_v1), detail, artefact(실패를 트리거한 경로 또는 schema_version)를 반환합니다. 타입이 지정된 게터: getStage(), getDetail(), getArtefact()입니다.
• 복구. 적합성 / DevOps 조치입니다. 입력 아티팩트 경로를 확인하거나, 깨끗한 실행에서 claims.json을 다시 생성하거나, 내보내기를 다시 시도하기 전에 매니페스트를 다시 빌드하십시오.

위반 값 객체

이들은 예외가 아닙니다. 엔진이 개별 위반을 기술하기 위해 반환하는 불변 값 객체입니다. getContext()를 담지 않습니다.

ComplianceViolation

• 무엇인가. 외부 검증기(veraPDF 또는 동등물)가 보고한 하나의 규칙 실패를 나타내는 final readonly 값 객체로, ISO 절 참조와 PDF 구조 내 위치를 포함합니다.
• 필드. public readonly 속성: ruleId(검증기 규칙 식별자, 예: 6.1.2-1), clause(ISO 절 참조, 예: ISO 19005-1:2005, 6.1.2), severity(예: error, warning), location(PDF 구조 내 객체 경로), message(사람이 읽을 수 있는 설명)입니다.
• 사용. 적합성 검증기가 반환한 컬렉션을 검사하십시오. 각 항목을 severity와 clause로 라우팅하거나 표시하십시오. PDF/A 및 PDF/UA 검증을 참조하십시오.

RuleViolation

• 무엇인가. 하나의 Schematron / EN 16931 비즈니스 규칙 위반을 나타내는 final readonly 값 객체로, SchematronRunnerInterface::runRules()가 반환하고 ValidationResult::$ruleViolations 내에 집계됩니다. 안정성은 experimental입니다.
• 필드. public readonly 속성: ruleId(EN 16931 식별자, 예: BR-{n}, BR-CO-{n}, BR-CL-{n}, BR-DEC-{n}, 또는 등급별 팩), severity(RuleSeverity 열거형), message(규칙 텍스트, en-GB), xpath(임베드된 XML로의 XPath, 문서 전체 규칙의 경우 null), semanticPath(점 표기 BG/BT 경로, 예: BG-22.BT-106, 구조적 위반의 경우 null)입니다.
• 사용. 검증 결과의 컬렉션을 검사하십시오. 각 항목을 severity, ruleId, 위치 지정자로 라우팅하거나 표시하십시오.

함께 보기

• 오류 참조 색인
• 지식 베이스 색인
• 서명 및 타임스탬프 실패
• 암호화 및 권한
• 폰트 및 태깅
• PDF/A 및 PDF/UA 검증