Erreurs de conformité

Portée

Ces entrées couvrent les deux exceptions de l’espace de noms NextPDF\Compliance\Exception. Les deux sont levées par le sous-système de conformité : le pipeline canonique de hachage de clause et le cycle de vie de la conformité (le cache Document Compliance Evidence, le promoteur audited-to-terminal et l’observateur de cooldown).

Les deux classes sont final et étendent NextPdfException, qui elle-même étend \RuntimeException et implémente ContextAwareExceptionInterface. Aucune sous-classe ne redéfinit getContext(), donc les deux héritent de l’implémentation de base, qui renvoie un tableau vide. Le détail de diagnostic est porté dans le message de l’exception, pas dans getContext(). Attrape l’un ou l’autre type en tant que NextPdfException, ou en tant que \RuntimeException si tu as des gestionnaires existants.

Exigences d’exécution de hachage de clause

ClauseHashRequirementException

• Quand elle est levée. Depuis ClauseHash::compute() lorsqu’à l’environnement d’exécution PHP de l’hôte il manque une exigence dure du pipeline canonique de hachage de clause. Actuellement, la seule exigence de ce type est ext-intl, utilisée pour la normalisation Unicode Normalization Form KC (NFKC). Le site de levée unique produit le message ClauseHash requires ext-intl for NFKC normalisation.
• Pourquoi elle échoue en mode fermé. composer.json impose ext-intl, donc ceci ne se déclenche que dans un environnement aval mal configuré qui empaquette NextPDF sans intl. Le pipeline refuse de calculer un condensat non normalisé NFKC plutôt que d’émettre silencieusement un hachage incompatible avec tous les autres consommateurs de hachage de clause.
• Contexte. getContext() renvoie un tableau vide. La cause est indiquée dans le message.
• Rétablissement. Action de l’opérateur : installe et active l’extension PHP intl sur l’hôte, puis réessaie. Il n’existe pas de contournement dans le code ; le condensat normalisé ne peut pas être produit sans elle.

Échecs du cycle de vie de la conformité

ComplianceLifecycleException

• Quand elle est levée. Depuis le sous-système de cycle de vie de la conformité lorsqu’un invariant structurel sur claims.json ou son pipeline de persistance est violé à l’exécution. Les sites de levée s’étendent sur le promoteur audited-to-terminal, l’observateur de cooldown et le cache incrémental Document Compliance Evidence. Les déclencheurs concrets sont :
  • Document racine malformé — claims.json ne se décode pas en objet, ou claims.standards n’est pas un objet JSON (par exemple, claims.json must decode to an object, claims.standards must be a JSON object, claims.json invalid JSON: <detail>).
  • Échecs de lecture — claims.json est manquant ou illisible (par exemple, claims.json not found at: <path>, claims.json unreadable at <path>).
  • Échecs d’E/S d’écriture atomique dans le pipeline de persistance — ouverture temp, flock, écriture courte, fflush, rename atomique et écriture du sidecar (par exemple, 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>).
  • Échecs côté encodeur — json_encode() rejette la charge utile sortante (par exemple, claims.json encode failed: <detail>).
  • Échecs d’amorçage du cache de preuves — le cache incrémental ne peut pas créer ou écrire son répertoire racine (par exemple, IncrementalEvidenceCache: cannot create rootDir <path>, IncrementalEvidenceCache: write failed for <path>, IncrementalEvidenceCache: rename failed for <path>).
  • Violations d’invariant interne — par exemple un gmdate produced empty timestamp ou fqClauseId: empty clauseKey.
• Pourquoi elle existe. C’est un remplacement à type de domaine de l’usage précédent de \RuntimeException dans le code de cycle de vie et de cache. Elle ne change pas le contrat d’exécution, parce que NextPdfException étend déjà \RuntimeException ; les clauses catch (\RuntimeException $e) existantes continuent de fonctionner.
• Contexte. getContext() renvoie un tableau vide. Le chemin fautif et l’échec spécifique sont nommés dans le message ; les échecs de décodage et d’encodage JSON chaînent aussi la \JsonException sous-jacente comme exception précédente, donc lis getPrevious() pour ceux-ci.
• Rétablissement.
  • Pour les erreurs de forme et de lecture, c’est une action de l’opérateur : inspecte claims.json au chemin nommé dans le message, confirme que c’est du JSON bien formé dont la racine et le membre standards sont des objets, et confirme qu’il est présent et lisible.
  • Pour les erreurs d’écriture atomique et d’amorçage de cache, vérifie l’existence, les permissions et l’espace libre du répertoire cible, puis réessaie.
  • Pour les échecs côté encodeur, c’est une action du développeur : la charge utile remise à json_encode() n’est pas encodable. Capture l’exception précédente chaînée et le message pour un rapport de défaut.

Voir aussi

• Index de la référence des erreurs
• Validation PDF/A et PDF/UA