Kesalahan kepatuhan

Cakupan

Entri-entri ini mencakup dua eksepsi dalam namespace NextPDF\Compliance\Exception. Keduanya dilemparkan oleh subsistem kepatuhan: pipeline clause-hash kanonis dan siklus hidup kepatuhan (cache Document Compliance Evidence, promoter audited-ke-terminal, dan observer cooldown).

Kedua kelas bersifat final dan memperluas NextPdfException, yang sendiri memperluas \RuntimeException dan mengimplementasikan ContextAwareExceptionInterface. Tidak ada subkelas yang menimpa getContext(), sehingga keduanya mewarisi implementasi basis, yang mengembalikan array kosong. Detail diagnostik dibawa dalam pesan eksepsi, bukan dalam getContext(). Tangkap salah satu tipe sebagai NextPdfException, atau sebagai \RuntimeException jika Anda memiliki penangan yang sudah ada.

Persyaratan runtime clause-hash

ClauseHashRequirementException

• Kapan dilemparkan. Dari ClauseHash::compute() ketika runtime PHP host kehilangan persyaratan keras dari pipeline clause-hash kanonis. Saat ini satu-satunya persyaratan tersebut adalah ext-intl, digunakan untuk normalisasi Unicode Normalization Form KC (NFKC). Satu-satunya situs throw memunculkan pesan ClauseHash requires ext-intl for NFKC normalisation.
• Mengapa gagal-tertutup. composer.json mewajibkan ext-intl, sehingga ini menyala hanya pada hilir yang salah konfigurasi yang mengemas NextPDF tanpa intl. Pipeline menolak menghitung digest non-NFKC-ternormalisasi alih-alih secara senyap memancarkan hash yang tidak kompatibel dengan setiap konsumen clause-hash lainnya.
• Konteks. getContext() mengembalikan array kosong. Penyebabnya dinyatakan dalam pesan.
• Pemulihan. Tindakan operator: pasang dan aktifkan ekstensi PHP intl pada host, lalu coba lagi. Tidak ada solusi dalam-kode; digest ternormalisasi tidak dapat dihasilkan tanpanya.

Kegagalan siklus hidup kepatuhan

ComplianceLifecycleException

• Kapan dilemparkan. Dari subsistem siklus hidup kepatuhan ketika sebuah invarian struktural pada claims.json atau pipeline persistensinya dilanggar pada saat runtime. Situs throw mencakup promoter audited-ke-terminal, observer cooldown, dan cache inkremental Document Compliance Evidence. Pemicu konkretnya adalah:
  • Dokumen root cacat — claims.json tidak terdekode menjadi objek, atau claims.standards bukan objek JSON (misalnya, claims.json must decode to an object, claims.standards must be a JSON object, claims.json invalid JSON: <detail>).
  • Kegagalan baca — claims.json hilang atau tidak dapat dibaca (misalnya, claims.json not found at: <path>, claims.json unreadable at <path>).
  • Kegagalan I/O atomic-write dalam pipeline persistensi — temp open, flock, short write, fflush, atomic rename, dan sidecar write (misalnya, 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>).
  • Kegagalan sisi-encoder — json_encode() menolak payload keluar (misalnya, claims.json encode failed: <detail>).
  • Kegagalan bootstrap evidence-cache — cache inkremental tidak dapat membuat atau menulis direktori root-nya (misalnya, IncrementalEvidenceCache: cannot create rootDir <path>, IncrementalEvidenceCache: write failed for <path>, IncrementalEvidenceCache: rename failed for <path>).
  • Pelanggaran invarian internal — misalnya sebuah gmdate produced empty timestamp atau fqClauseId: empty clauseKey.
• Mengapa eksepsi ini ada. Ini adalah pengganti bertipe-domain untuk penggunaan \RuntimeException sebelumnya dalam kode siklus hidup dan cache. Eksepsi ini tidak mengubah kontrak runtime, karena NextPdfException sudah memperluas \RuntimeException; klausa catch (\RuntimeException $e) yang sudah ada tetap berfungsi.
• Konteks. getContext() mengembalikan array kosong. Jalur yang bermasalah dan kegagalan spesifik disebut dalam pesan; kegagalan JSON-decode dan encode juga merangkai \JsonException yang mendasarinya sebagai eksepsi sebelumnya, jadi baca getPrevious() untuk yang itu.
• Pemulihan.
  • Untuk kesalahan bentuk dan baca, ini adalah tindakan operator: periksa claims.json pada jalur yang disebut dalam pesan, pastikan ia merupakan JSON terbentuk-baik yang root dan member standards-nya adalah objek, dan pastikan ia hadir dan dapat dibaca.
  • Untuk kesalahan atomic-write dan cache-bootstrap, periksa keberadaan, izin, dan ruang bebas direktori target, lalu coba lagi.
  • Untuk kegagalan sisi-encoder, ini adalah tindakan pengembang: payload yang diserahkan ke json_encode() tidak dapat dienkode. Tangkap eksepsi sebelumnya yang terangkai dan pesan untuk laporan cacat.

Lihat juga

• Indeks referensi kesalahan
• Validasi PDF/A dan PDF/UA