적합성 오류

범위

이 항목들은 NextPDF\Compliance\Exception 네임스페이스의 두 가지 예외를 다룹니다. 둘 다 적합성 서브시스템에서 발생합니다. 표준 절 해시 파이프라인과 적합성 수명 주기(Document Compliance Evidence 캐시, 감사 대상에서 종단 상태로 승격하는 승격기, 그리고 쿨다운 옵저버)입니다.

두 클래스 모두 final이며 NextPdfException을 확장합니다. NextPdfException 자체는 \RuntimeException을 확장하고 ContextAwareExceptionInterface를 구현합니다. 두 서브클래스 모두 getContext()를 재정의하지 않으므로, 둘 다 빈 배열을 반환하는 기반 구현을 상속합니다. 진단 세부 정보는 getContext()가 아니라 예외 메시지에 담깁니다. 두 타입 모두 NextPdfException으로 잡거나, 기존 핸들러가 있다면 \RuntimeException으로 잡으십시오.

절 해시 런타임 요구 사항

ClauseHashRequirementException

• 발생 시점. 호스트 PHP 런타임이 표준 절 해시 파이프라인의 강한 요구 사항을 누락했을 때 ClauseHash::compute()에서 발생합니다. 현재 유일한 요구 사항은 유니코드 정규화 형식 KC(NFKC) 정규화에 사용되는 ext-intl입니다. 단일 발생 지점은 ClauseHash requires ext-intl for NFKC normalisation 메시지를 발생시킵니다.
• 왜 fail-closed로 실패하는가. composer.json은 ext-intl을 필수로 지정하므로, 이는 intl 없이 NextPDF를 패키징한 잘못 구성된 다운스트림에서만 발생합니다. 파이프라인은 다른 모든 절 해시 소비자와 호환되지 않는 해시를 조용히 내보내는 대신, NFKC로 정규화되지 않은 다이제스트를 계산하기를 거부합니다.
• 컨텍스트. getContext()는 빈 배열을 반환합니다. 원인은 메시지에 명시됩니다.
• 복구. 운영자 조치입니다. 호스트에 PHP intl 확장을 설치하고 활성화한 뒤 재시도하십시오. 코드 내 우회책은 없습니다. 정규화된 다이제스트는 이것 없이는 생성할 수 없습니다.

적합성 수명 주기 실패

ComplianceLifecycleException

• 발생 시점. claims.json 또는 그 영속화 파이프라인의 구조적 불변식이 런타임에 위반되었을 때 적합성 수명 주기 서브시스템에서 발생합니다. 발생 지점은 감사 대상에서 종단 상태로 승격하는 승격기, 쿨다운 옵저버, Document Compliance Evidence 증분 캐시에 걸쳐 있습니다. 구체적인 트리거는 다음과 같습니다.
  • 잘못된 형식의 루트 문서 — claims.json이 객체로 디코딩되지 않거나, claims.standards가 JSON 객체가 아닙니다(예: claims.json must decode to an object, claims.standards must be a JSON object, claims.json invalid JSON: <detail>).
  • 읽기 실패 — claims.json이 없거나 읽을 수 없습니다(예: claims.json not found at: <path>, claims.json unreadable at <path>).
  • 영속화 파이프라인의 원자적 쓰기 I/O 실패 — temp 열기, flock, 짧은 쓰기, fflush, 원자적 rename, 사이드카 쓰기(예: tmp open failed at <path>, tmp flock failed at <path>, tmp write short for <path>, tmp fflush failed at <path>, atomic rename failed for <path>, sha256 sidecar write failed at <path>).
  • 인코더 측 실패 — json_encode()가 보낼 페이로드를 거부합니다(예: claims.json encode failed: <detail>).
  • 증거 캐시 부트스트랩 실패 — 증분 캐시가 루트 디렉터리를 생성하거나 쓸 수 없습니다(예: IncrementalEvidenceCache: cannot create rootDir <path>, IncrementalEvidenceCache: write failed for <path>, IncrementalEvidenceCache: rename failed for <path>).
  • 내부 불변식 위반 — 예를 들어 gmdate produced empty timestamp나 fqClauseId: empty clauseKey입니다.
• 존재 이유. 이는 수명 주기 및 캐시 코드에서 이전에 사용하던 \RuntimeException을 도메인 타입으로 대체한 것입니다. NextPdfException이 이미 \RuntimeException을 확장하므로 런타임 계약을 바꾸지 않습니다. 기존 catch (\RuntimeException $e) 절은 계속 작동합니다.
• 컨텍스트. getContext()는 빈 배열을 반환합니다. 문제가 된 경로와 구체적인 실패는 메시지에 명시됩니다. JSON 디코딩 및 인코딩 실패는 기저의 \JsonException을 이전 예외로도 연결하므로, 그런 경우에는 getPrevious()를 읽으십시오.
• 복구.
  • 형태 및 읽기 오류의 경우 운영자 조치입니다. 메시지에 명시된 경로에서 claims.json을 검사하여 루트와 standards 멤버가 객체인 올바른 형식의 JSON인지 확인하고, 파일이 존재하며 읽을 수 있는지 확인하십시오.
  • 원자적 쓰기 및 캐시 부트스트랩 오류의 경우, 대상 디렉터리의 존재 여부, 권한, 여유 공간을 확인한 뒤 재시도하십시오.
  • 인코더 측 실패의 경우 개발자 조치입니다. json_encode()에 전달된 페이로드가 인코딩 가능하지 않습니다. 결함 보고를 위해 연결된 이전 예외와 메시지를 캡처하십시오.

함께 보기

• 오류 참조 색인
• PDF/A 및 PDF/UA 검증