合規錯誤

適用範圍

下列條目涵蓋 NextPDF\Compliance\Exception 命名空間中的兩個例外狀況。兩者皆由合規子系統拋出：標準子句雜湊管線與合規生命週期（Document Compliance Evidence 快取、已稽核轉終態的推進器，以及冷卻觀察器）。

兩個類別都是 final，並繼承自 NextPdfException；而後者本身繼承 \RuntimeException 並實作 ContextAwareExceptionInterface。兩個子類別都未覆寫 getContext()，因此都沿用回傳空陣列的基底實作。診斷細節攜帶在例外狀況的訊息中，而非 getContext()。你可以把任一型別當作 NextPdfException 攔截；若你已有既存的處理器，也可當作 \RuntimeException 攔截。

子句雜湊的執行階段需求

ClauseHashRequirementException

• 何時被拋出。 當主機 PHP 執行階段缺少標準子句雜湊管線的硬性需求時，從 ClauseHash::compute() 拋出。目前唯一的此類需求是 ext-intl，用於 Unicode 正規化形式 KC（NFKC）正規化。唯一的拋出點會產生 ClauseHash requires ext-intl for NFKC normalisation 這則訊息。
• 為何失敗即關閉。 composer.json 已強制要求 ext-intl，因此只有在下游配置錯誤、把 NextPDF 打包時排除了 intl 的情況下才會觸發。管線寧可拒絕計算未經 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 失敗 — 暫存檔開啟、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。
• 為何存在。 這是生命週期與快取程式碼中先前使用 \RuntimeException 的領域具型別替代品。它不會改變執行階段合約，因為 NextPdfException 本就繼承自 \RuntimeException；既有的 catch (\RuntimeException $e) 子句仍可正常運作。
• 脈絡。 getContext() 回傳空陣列。出問題的路徑與具體的失敗會敘明於訊息中；JSON 解碼與編碼失敗也會把底層的 \JsonException 鏈結為前一個例外狀況，因此可讀取 getPrevious() 取得這些資訊。
• 解法。
  • 對於格式與讀取錯誤，這是維運動作：檢視訊息所指路徑的 claims.json，確認它是格式正確的 JSON 且其根與 standards 成員皆為物件，並確認它存在且可讀取。
  • 對於原子寫入與快取啟動錯誤，請檢查目標目錄的存在與否、權限與可用空間，然後重試。
  • 對於編碼端失敗，這是開發者動作：交給 json_encode() 的酬載無法編碼。請擷取鏈結的前一個例外狀況與訊息，作為缺陷回報。

另請參閱

• 錯誤參考索引
• PDF/A 與 PDF/UA 驗證