문제 해결 기술 자료

이 기술 자료가 다루는 내용

이 기술 자료는 관찰된 실패를 원인 및 해결 방법과 연결합니다. 모든 항목은 추측이 아니라 엔진 자체의 예외 클래스, 실패 경로 테스트, 소스 가드를 근거로 합니다. 엔진 안에 특정 실패를 발생시키는 코드 경로가 없다면, 이 기술 자료에서도 그러한 실패를 임의로 만들어 내지 않습니다.

이 기술 자료는 네 개의 주제 페이지로 구성됩니다.

서명 검증 — 잘못된 서명, 불완전한 체인, 해지 상태를 알 수 없음, 타임스탬프 실패.
PDF/A 및 PDF/UA 검증 — 출력 인텐트 누락, 태그가 없는 콘텐츠, 언어 누락, 글꼴 임베딩 실패.
글꼴 및 태깅 — 글꼴을 찾을 수 없음, 서브셋팅, CJK 커버리지, 구조 트리 문제.
암호화 및 권한 — 복호화 실패와 권한 플래그 경계.

항목을 읽는 방법

각 항목은 다섯 부분으로 구성됩니다.

증상 — 관찰되는 내용입니다. 예외 클래스, 메시지 일부 또는 하위 검증기의 판정이 포함됩니다.
유력한 원인 — 엔진이 보고하는 입력 또는 구성상의 조건입니다.
증거 / 진단 — 원인을 확인하는 방법입니다. 여기서는 해당 동작을 보여 주는 정확한 예외 클래스, getContext() 필드 또는 테스트를 명시하므로 추측하지 않고 직접 확인할 수 있습니다.
해결 방법 — 원인을 제거하는 단계입니다. 순서가 있는 절차로 작성되어 있습니다.
관련 항목 — 다음으로 읽어야 할 모듈 참조 페이지 또는 형제 항목입니다.

예외 유형으로 실패 식별하기

NextPDF는 오류를 문자열 오류 코드가 아니라 PHP 클래스로 식별합니다. 예외 클래스에는 NPDF-#### 상수가 없습니다. 대상을 좁혀 대응하려면 리프 예외를 잡고, 구조화된 진단 필드를 얻으려면 ContextAwareExceptionInterface::getContext()를 읽습니다. 기본 유형은 NextPDF\Exception\NextPdfException이며, 보안 실패에는 추가로 NextPDF\Security\Exception\SecurityException을 사용합니다.

전체 계층 구조와 catch 순서 규칙은 예외 참조에서 확인할 수 있습니다.

<?php

declare(strict_types=1);

use NextPDF\Exception\NextPdfException;
use NextPDF\Contracts\ContextAwareExceptionInterface;

try {
    // ... engine call ...
} catch (NextPdfException $e) {
    $context = $e instanceof ContextAwareExceptionInterface
        ? $e->getContext()
        : [];
    \error_log($e->getMessage());
    // $context carries snake_case primitive fields safe to serialize.
}

범위와 경계

이 기술 자료는 엔진 내부의 실패 감지와 보고를 설명합니다. veraPDF나 callas와 같은 외부 검증기의 적합성 판정은 설명하지 않습니다. 이러한 도구는 자체 규칙 집합을 적용합니다. 엔진이 문서를 프로필 내에 유지하기 위해 작업을 거부하는 경우 — 예를 들어 PDF/A에서 암호화를 거부하는 경우 — 해당 항목은 그 동작을 규정하는 조항과 이를 강제하는 예외를 인용합니다.

참고 항목

예외 참조 — 전체 계층 구조, catch 순서, getContext() 계약
적합성 참조 — PDF/A, PDF/UA, PDF/X 프로필 검사기

용어집: 컨텍스트 인식 예외