合规错误

范围

这些条目涵盖 NextPDF\Compliance\Exception 命名空间中的两个异常。二者都由合规子系统抛出：规范的条款哈希流水线和合规生命周期（Document Compliance Evidence 缓存、audited-to-terminal 提升器，以及冷却观察器）。

两个类都是 final 且继承 NextPdfException，而后者本身继承 \RuntimeException 并实现 ContextAwareExceptionInterface。两个子类都不重写 getContext()，因此二者都继承基类实现， 后者返回一个空数组。诊断细节携带在异常消息中，而非 getContext() 中。请以 NextPdfException 捕获任一类型，或者如果你有现成的处理器，则以 \RuntimeException 捕获。

条款哈希运行时要求

ClauseHashRequirementException

• When it is thrown. 当宿主 PHP 运行时缺少规范条款哈希流水线的一个硬性要求时，由 ClauseHash::compute() 抛出。 目前唯一这样的要求是 ext-intl，用于 Unicode Normalization Form KC（NFKC）规范化。那个唯一的抛出站点会抛出消息 ClauseHash requires ext-intl for NFKC normalisation。
• Why it fails closed. composer.json 强制要求 ext-intl，因此它只会在一个把 NextPDF 打包时不带 intl 的、配置错误的下游中触发。该流水线会拒绝计算一个未经 NFKC 规范化的摘要，而非静默地发出一个与其他每个条款哈希消费方都不兼容的哈希。
• Context. getContext() 返回一个空数组。原因在消息中说明。
• Recovery. 运维操作：在宿主上安装并启用 PHP intl 扩展， 然后重试。没有代码内的变通方案；没有它就无法产生规范化的摘要。

合规生命周期失败

ComplianceLifecycleException

• When it is thrown. 当 claims.json 或其持久化流水线上的某个结构不变量在运行时被违反时，由合规生命周期子系统抛出。抛出站点横跨 audited-to-terminal 提升器、冷却观察器，以及 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 失败 — 临时文件打开、 flock、短写、fflush、原子 rename，以及 sidecar 写入（例如， 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>）。
  • Evidence 缓存引导失败 — 增量缓存无法创建或写入其根目录（例如， IncrementalEvidenceCache: cannot create rootDir <path>、 IncrementalEvidenceCache: write failed for <path>、 IncrementalEvidenceCache: rename failed for <path>）。
  • 内部不变量破坏 — 例如一个 gmdate produced empty timestamp 或 fqClauseId: empty clauseKey。
• Why it exists. 这是对生命周期与缓存代码中先前使用的 \RuntimeException 的一个领域类型化替代品。它不改变运行时契约，因为 NextPdfException 已经继承 \RuntimeException；现有的 catch (\RuntimeException $e) 子句会继续工作。
• Context. getContext() 返回一个空数组。出问题的路径和具体的失败都在消息中指明；JSON 解码与编码失败也会把底层的 \JsonException 链接为前一个异常，因此对于那些情况请读取 getPrevious()。
• Recovery.
  • 对于形态与读取错误，这是一个运维操作：检查消息中所指名路径处的 claims.json，确认它是良构的 JSON，其根和 standards 成员都是对象，并确认它存在且可读。
  • 对于原子写入与缓存引导错误，检查目标目录的存在、权限和可用空间，然后重试。
  • 对于编码器侧失败，这是一个开发者操作：交给 json_encode() 的负载不可编码。为一份缺陷报告捕获链接的前一个异常和消息。

另请参阅

• Error reference index
• PDF/A and PDF/UA validation