콘텐츠로 이동
NextPDF
getnextpdf.com

오류 참조

이 문서는 NextPDF Core가 발생시키는 예외를 영역별로 정리한 참조 목록입니다. 각 범주 페이지는 클래스별로 언제 발생하는지, 어떤 구조화된 데이터를 담는지, 그리고 어떻게 복구하는지를 설명합니다. 특정 클래스를 잡기보다 증상을 진단하고 있다면, 대신 문제 해결 가이드부터 시작하십시오. 이 가이드는 관찰한 현상을 기준으로 정리되어 있습니다.

한눈에 보기

섹션 제목: “한눈에 보기”
  • 대부분의 예외는 단일 기반 클래스 NextPdfException을 확장하므로, 하나의 catch 블록으로 전체 계열을 잡을 수 있습니다.
  • NextPdfException은 컨텍스트 인식형입니다. getContext(): array를 선언하는 ContextAwareExceptionInterface를 구현합니다. 많은 서브클래스가 getContext()를 재정의하여 구조화된 진단 키를 반환하며, 나머지는 비어 있는 기본값을 상속하고 메시지와 타입이 지정된 게터를 통해 세부 정보를 노출합니다.
  • 소수의 저수준 예외는 NextPdfException이 아니라 PHP의 \RuntimeException을 직접 확장합니다. 이들은 컨텍스트 인식형이 아니며, 세부 정보를 public readonly 속성에 담습니다. 각 범주 페이지에서 이를 명시적으로 표시합니다.
  • …Violation으로 이름 붙은 두 적합성 타입(ComplianceViolation, RuleViolation)은 예외가 아니라 값 객체입니다. 발생하지 않으며 발견 사항을 기술합니다.

기반 타입과 컨텍스트 계약

섹션 제목: “기반 타입과 컨텍스트 계약”

NextPdfException은 \RuntimeException을 확장하고 ContextAwareExceptionInterface를 구현하는 추상 클래스입니다. 계약은 작습니다.

interface ContextAwareExceptionInterface
{
    /** @return array<string, mixed> structured, log-safe diagnostic context */
    public function getContext(): array;
}

따라서 방어적인 핸들러는 다음과 같은 모습입니다.

use NextPDF\Exception\NextPdfException;


try {
    // … NextPDF operation …
} catch (NextPdfException $e) {
    $logger->error($e->getMessage(), $e->getContext());
    // getContext() returns [] when a subclass does not override it;
    // the message and any typed getters still carry the detail.
}

일부 실패는 그대로 \RuntimeException으로 표면화되므로(범주별 참고 사항 참조), 방어를 이중으로 두는 경계에서는 \RuntimeException도 함께 잡아 구체 타입을 검사할 수 있습니다.

범주

섹션 제목: “범주”
  • Core 및 일반 오류 — 문서, 병합, 접근성, 전자 송장, 색 공간, 값 객체, strict 모드 실패와 공유 기반 타입을 다룹니다.
  • 보안, 서명, PKI 오류 — 서명 생성과 검증, 타임스탬프, PKI 경로 및 이름 제약 검증, 해싱, 무결성, PKCS#11을 다룹니다.
  • 렌더링 및 I/O 오류 — HTML 레이아웃과 페이지 미디어, 폰트와 텍스트 셰이핑, 라이터와 리더, XMP 메타데이터를 다룹니다.
  • 런타임 및 지원 오류 — HTTP 전송, 회복탄력성(서킷 브레이커, 저하 모드), 관측성, 매니페스트 처리를 다룹니다.
  • Accelerator 오류 — 선택적 가속 사이드카 전송을 다룹니다.
  • 적합성 오류 — 절 해시 요구 사항과 적합성 수명 주기를 다룹니다.

함께 보기

섹션 제목: “함께 보기”