错误参考

这是 NextPDF Core 抛出的异常的参考清单，按领域组织。每个类别页面会逐类记录它在何时被抛出、携带哪些结构化数据，以及如何恢复。如果你是在诊断某个症状，而不是捕获某个具体的类，请改从故障排查指南开始——它们是按你所观察到的现象组织的。

速览

• 大多数异常都继承自同一个基类 NextPdfException，因此你可以用一个 catch 块捕获整个家族。
• NextPdfException 是上下文感知的：它实现了 ContextAwareExceptionInterface，该接口声明了 getContext(): array。许多子类会重写 getContext() 以返回结构化的诊断键；其他子类则继承空的默认实现，并通过消息和类型化的 getter 暴露其细节。
• 少数底层异常直接继承 PHP 的 \RuntimeException，而非 NextPdfException。这些异常不是上下文感知的，它们的细节携带在公开的 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 and general errors — 文档、合并、无障碍、电子发票、颜色空间、值对象以及严格模式的失败，外加共享的基类型。
• Security, signing, and PKI errors — 签名的创建与验证、时间戳、PKI 路径与名称约束验证、哈希、完整性，以及 PKCS#11。
• Rendering and I/O errors — HTML 布局与分页媒体、字体与文本整形、写入器与读取器，以及 XMP 元数据。
• Runtime and support errors — HTTP 传输、弹性（断路器、降级模式）、可观测性，以及清单处理。
• Accelerator errors — 可选的加速边车传输。
• Compliance errors — 条款哈希要求与合规生命周期。

另请参阅

• Troubleshooting — 按症状组织的指南，涵盖签名验证、加密与权限、字体与标记，以及 PDF/A 与 PDF/UA 验证。