Errori di conformità

Ambito

Queste voci coprono le due eccezioni nel namespace NextPDF\Compliance\Exception. Entrambe sono sollevate dal sottosistema di conformità: la pipeline canonica di clause-hash e il ciclo di vita della conformità (la cache Document Compliance Evidence, il promotore da audited a terminal e l’observer di cooldown).

Entrambe le classi sono final ed estendono NextPdfException, che a sua volta estende \RuntimeException e implementa ContextAwareExceptionInterface. Nessuna delle due sottoclassi sovrascrive getContext(), perciò entrambe ereditano l’implementazione di base, che restituisce un array vuoto. Il dettaglio diagnostico è trasportato nel messaggio dell’eccezione, non in getContext(). Intercettare entrambi i tipi come NextPdfException, oppure come \RuntimeException se si dispone di gestori esistenti.

Requisiti di runtime di clause-hash

ClauseHashRequirementException

• Quando viene sollevata. Da ClauseHash::compute() quando al runtime PHP dell’host manca un requisito imprescindibile della pipeline canonica di clause-hash. Attualmente l’unico requisito di questo genere è ext-intl, usato per la normalizzazione Unicode Normalization Form KC (NFKC). L’unico punto di throw solleva il messaggio ClauseHash requires ext-intl for NFKC normalisation.
• Perché adotta il fail-closed. composer.json impone ext-intl, perciò questa scatta solo in un downstream mal configurato che impacchetta NextPDF senza intl. La pipeline rifiuta di calcolare un digest non normalizzato NFKC anziché emettere silenziosamente un hash incompatibile con ogni altro consumatore di clause-hash.
• Contesto. getContext() restituisce un array vuoto. La causa è dichiarata nel messaggio.
• Recupero. Azione dell’operatore: installare e abilitare l’estensione PHP intl sull’host, quindi riprovare. Non esiste alcuna soluzione alternativa nel codice; il digest normalizzato non può essere prodotto senza di essa.

Guasti del ciclo di vita della conformità

ComplianceLifecycleException

• Quando viene sollevata. Dal sottosistema del ciclo di vita della conformità quando un’invariante strutturale su claims.json o sulla sua pipeline di persistenza viene violata a runtime. I punti di throw spaziano dal promotore da audited a terminal, all’observer di cooldown, alla cache incrementale Document Compliance Evidence. I trigger concreti sono:
  • Documento radice malformato — claims.json non si decodifica in un oggetto, oppure claims.standards non è un oggetto JSON (ad esempio, claims.json must decode to an object, claims.standards must be a JSON object, claims.json invalid JSON: <detail>).
  • Guasti di lettura — claims.json è mancante o illeggibile (ad esempio, claims.json not found at: <path>, claims.json unreadable at <path>).
  • Guasti di I/O della scrittura atomica nella pipeline di persistenza — apertura del temp, flock, scrittura corta, fflush, rename atomico e scrittura del sidecar (ad esempio, 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>).
  • Guasti lato encoder — json_encode() rifiuta il payload in uscita (ad esempio, claims.json encode failed: <detail>).
  • Guasti di bootstrap della evidence-cache — la cache incrementale non può creare o scrivere la propria directory radice (ad esempio, IncrementalEvidenceCache: cannot create rootDir <path>, IncrementalEvidenceCache: write failed for <path>, IncrementalEvidenceCache: rename failed for <path>).
  • Violazioni di invarianti interne — ad esempio un gmdate produced empty timestamp o fqClauseId: empty clauseKey.
• Perché esiste. È una sostituzione tipizzata per dominio del precedente uso di \RuntimeException nel codice del ciclo di vita e della cache. Non cambia il contratto a runtime, perché NextPdfException estende già \RuntimeException; le clausole catch (\RuntimeException $e) esistenti continuano a funzionare.
• Contesto. getContext() restituisce un array vuoto. Il percorso problematico e il guasto specifico sono indicati nel messaggio; i guasti di decode ed encode JSON concatenano inoltre la \JsonException sottostante come eccezione precedente, perciò leggere getPrevious() per quei casi.
• Recupero.
  • Per gli errori di forma e di lettura, questa è un’azione dell’operatore: ispezionare claims.json al percorso indicato nel messaggio, confermare che sia JSON ben formato la cui radice e il cui membro standards siano oggetti, e confermare che sia presente e leggibile.
  • Per gli errori di scrittura atomica e di bootstrap della cache, verificare l’esistenza, i permessi e lo spazio libero della directory di destinazione, quindi riprovare.
  • Per i guasti lato encoder, questa è un’azione dello sviluppatore: il payload passato a json_encode() non è codificabile. Acquisire l’eccezione precedente concatenata e il messaggio per una segnalazione di difetto.

Vedere anche

• Indice del riferimento degli errori
• Convalida PDF/A e PDF/UA