Compliance-Fehler

Geltungsbereich

Diese Einträge decken die zwei Exceptions im Namespace NextPDF\Compliance\Exception ab. Beide werden vom Compliance-Subsystem ausgelöst: der kanonischen Klausel-Hash-Pipeline und dem Compliance-Lebenszyklus (dem Document-Compliance- Evidence-Cache, dem Audited-to-Terminal-Promoter und dem Cooldown-Observer).

Beide Klassen sind final und erweitern NextPdfException, das selbst \RuntimeException erweitert und ContextAwareExceptionInterface implementiert. Keine Unterklasse überschreibt getContext(), sodass beide die Basisimplementierung erben, die ein leeres Array zurückgibt. Das Diagnosedetail wird in der Exception- Meldung getragen, nicht in getContext(). Fangen Sie einen der Typen als NextPdfException ab, oder als \RuntimeException, wenn Sie bestehende Handler haben.

Klausel-Hash-Laufzeitanforderungen

ClauseHashRequirementException

• Wann sie ausgelöst wird. Aus ClauseHash::compute(), wenn der Host-PHP-Laufzeit eine harte Anforderung der kanonischen Klausel-Hash-Pipeline fehlt. Derzeit ist die einzige solche Anforderung ext-intl, verwendet für Unicode- Normalization-Form-KC-(NFKC-)Normalisierung. Die einzige Throw-Site löst die Meldung ClauseHash requires ext-intl for NFKC normalisation aus.
• Warum sie fail-closed reagiert. composer.json schreibt ext-intl vor, sodass dies nur in einem fehlkonfigurierten Downstream auslöst, das NextPDF ohne intl paketiert. Die Pipeline weigert sich, einen nicht-NFKC-normalisierten Digest zu berechnen, statt stillschweigend einen Hash auszugeben, der mit jedem anderen Klausel-Hash-Konsumenten inkompatibel ist.
• Kontext. getContext() gibt ein leeres Array zurück. Die Ursache steht in der Meldung.
• Behebung. Betriebsmaßnahme: Installieren und aktivieren Sie die PHP-intl-Erweiterung auf dem Host, und versuchen Sie es dann erneut. Es gibt keinen In-Code-Workaround; der normalisierte Digest kann ohne sie nicht erzeugt werden.

Compliance-Lifecycle-Fehler

ComplianceLifecycleException

• Wann sie ausgelöst wird. Aus dem Compliance-Lifecycle-Subsystem, wenn eine strukturelle Invariante an claims.json oder seiner Persistenz-Pipeline zur Laufzeit verletzt wird. Throw-Sites umfassen den Audited-to-Terminal-Promoter, den Cooldown- Observer und den inkrementellen Document-Compliance-Evidence-Cache. Die konkreten Auslöser sind:
  • Fehlerhaftes Root-Dokument — claims.json dekodiert nicht zu einem Objekt, oder claims.standards ist kein JSON-Objekt (zum Beispiel, claims.json must decode to an object, claims.standards must be a JSON object, claims.json invalid JSON: <detail>).
  • Lesefehler — claims.json fehlt oder ist nicht lesbar (zum Beispiel, claims.json not found at: <path>, claims.json unreadable at <path>).
  • Atomic-Write-I/O-Fehler in der Persistenz-Pipeline — Temp-Open, flock, Short Write, fflush, atomares rename und Sidecar-Write (zum Beispiel, 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>).
  • Encoder-seitige Fehler — json_encode() lehnt die ausgehende Payload ab (zum Beispiel, claims.json encode failed: <detail>).
  • Evidence-Cache-Bootstrap-Fehler — der inkrementelle Cache kann sein Root-Verzeichnis nicht erstellen oder beschreiben (zum Beispiel, IncrementalEvidenceCache: cannot create rootDir <path>, IncrementalEvidenceCache: write failed for <path>, IncrementalEvidenceCache: rename failed for <path>).
  • Interne Invariantenverletzungen — zum Beispiel ein gmdate produced empty timestamp oder fqClauseId: empty clauseKey.
• Warum sie existiert. Dies ist ein domänen-typisierter Ersatz für die frühere Verwendung von \RuntimeException im Lifecycle- und Cache-Code. Es ändert den Laufzeitvertrag nicht, weil NextPdfException bereits \RuntimeException erweitert; bestehende catch (\RuntimeException $e)-Klauseln funktionieren weiter.
• Kontext. getContext() gibt ein leeres Array zurück. Der betreffende Pfad und der spezifische Fehler werden in der Meldung genannt; JSON-Dekodier- und Kodierfehler verketten außerdem die zugrunde liegende \JsonException als vorherige Exception, lesen Sie also getPrevious() für diese.
• Behebung.
  • Bei Shape- und Lesefehlern ist dies eine Betriebsmaßnahme: Inspizieren Sie claims.json am in der Meldung genannten Pfad, bestätigen Sie, dass es wohlgeformtes JSON ist, dessen Root und standards-Member Objekte sind, und bestätigen Sie, dass es vorhanden und lesbar ist.
  • Bei Atomic-Write- und Cache-Bootstrap-Fehlern prüfen Sie Existenz, Berechtigungen und freien Speicherplatz des Zielverzeichnisses, und versuchen Sie es dann erneut.
  • Bei Encoder-seitigen Fehlern ist dies eine Entwicklermaßnahme: Die an json_encode() übergebene Payload ist nicht kodierbar. Erfassen Sie die verkettete vorherige Exception und die Meldung für einen Defektbericht.

Siehe auch

• Index der Fehlerreferenz
• PDF/A- und PDF/UA-Validierung