Kesalahan inti dan umum

Cakupan

Entri-entri ini mencakup eksepsi inti dan serbaguna yang dimunculkan NextPDF. Sebagian besar memperluas basis NextPdfException, yang sendiri memperluas \RuntimeException dan mengimplementasikan ContextAwareExceptionInterface. Antarmuka tersebut memaparkan satu metode, getContext(): array, yang mengembalikan peta snake_case datar berisi primitif yang aman diserialisasi ke log atau payload APM.

Tangkap keluarga NextPdfException dengan satu catch (NextPdfException $e). Tambahkan pula catch (\RuntimeException $e) untuk mencakup beberapa kesalahan tingkat rendah dalam himpunan ini yang memperluas \RuntimeException secara langsung (tercantum di bawah). Basis NextPdfException::getContext() mengembalikan array kosong; subkelas menimpanya untuk menambahkan bidang domain. Bila sebuah kelas tidak menimpa getContext(), kelas tersebut mewarisi array kosong dan detail diagnostiknya justru berada di dalam pesan serta getter bertipe.

Empat tipe dalam himpunan ini tidak memperluas NextPdfException: BlackPointCompensationUnsupportedException dan UnsupportedSourceDocumentException memperluas \RuntimeException secara langsung (tangkap keduanya sebagai \RuntimeException), serta ComplianceViolation dan RuleViolation adalah objek nilai, bukan eksepsi — keduanya didokumentasikan di sini karena memodelkan data kesalahan dan pelanggaran yang dikembalikan mesin.

Eksepsi basis

NextPdfException

• Apa ini. Basis abstract untuk keluarga eksepsi NextPDF utama di seluruh core dan paket ekstensinya. Kelas ini memperluas \RuntimeException dan mengimplementasikan ContextAwareExceptionInterface. Menangkap tipe tunggal ini mencegat keluarga NextPdfException; beberapa kesalahan yang memperluas \RuntimeException secara langsung (tercantum di atas) memerlukan penangkap \RuntimeException pula.
• Konteks. Basis getContext() mengembalikan array kosong. Subkelas menimpanya untuk mengembalikan bidang spesifik-domain.
• Pemulihan. Tidak dilemparkan secara langsung. Gunakan sebagai tipe penangkap-segala; bercabanglah pada subkelas konkret untuk penanganan spesifik.

Konfigurasi dan feature gating

InvalidConfigException

• Kapan dilemparkan. Ketika sebuah nilai Config atau kombinasi nilai tidak valid — sebuah pengaturan wajib yang hilang, opsi yang saling eksklusif, atau nilai di luar rentang yang diterimanya. Ini menandakan kesalahan pengembang: kode pemanggil menyuplai konfigurasi yang harus diperbaiki sebelum dicoba ulang. Pesan tersebut melaporkan kunci, tipe atau rentang yang diharapkan, dan tipe debug aktual dari nilai yang disuplai.
• Konteks. getContext() mengembalikan config_key, given_value, dan expected_type. Getter bertipe: getConfigKey(), getGivenValue(), getExpectedType().
• Pemulihan. Tindakan pengembang: perbaiki kunci konfigurasi yang disebut menjadi nilai bertipe atau berentang yang diharapkan sebelum memanggil NextPDF lagi.

NotImplementedException

• Kapan dilemparkan. Ketika titik masuk API publik tercapai tetapi implementasinya sengaja tidak ada dalam rilis saat ini. Digunakan untuk shim usang yang ada untuk memberi pemanggil pra-bisect kegagalan yang lantang dan dapat ditindaklanjuti, alih-alih no-op yang senyap. Pesan tersebut menggabungkan label feature yang dapat di-grep mesin dan referensi followUp (ID cacat, jangkar pelacakan, atau nama sprint).
• Konteks. Tidak menimpa getContext(), sehingga mengembalikan array kosong. Nilai $feature dan $followUp adalah properti readonly publik dan disematkan dalam pesan.
• Pemulihan. Tindakan pemanggil-pustaka: hapus panggilan tersebut, atau pin ke rilis mendatang yang mendaratkan follow-up yang disebut.

IncompatibleFeatureFlagsException

• Kapan dilemparkan. Pada saat build Config (Config::validate()) ketika kombinasi CssFeatureFlags tidak konsisten secara internal — satu flag mengandaikan flag lain yang dinonaktifkan. Satu-satunya kombinasi terlarang saat ini adalah layoutSubgrid = true dengan layoutGrid = false: sumbu ber-subgrid menurunkan garis gridnya dari kontainer grid induk (CSS Grid Layout Module Level 2 §1), sehingga subgrid tanpa grid menggambarkan grid yang tidak mungkin ada. Pemeriksaan ini berjalan terhadap flag yang teresolusi, sehingga CssRenderingMode::Safe (yang memaksa setiap fitur Phase 4+ nonaktif) menutupi kombinasi tersebut alih-alih memicunya. Memperluas StrictModeViolation.
• Konteks. getContext() menggabungkan bidang strict-mode induk (cssDeviation, excId, chunkSha256, location) dengan boolean layoutGrid dan layoutSubgrid. location adalah Config::validate() dan cssDeviation mengkodekan pasangan flag tersebut.
• Pemulihan. Tindakan pemanggil-pustaka: aktifkan layoutGrid bersama layoutSubgrid, atau nonaktifkan layoutSubgrid.

IncompatibleRenderingModeException

• Kapan dilemparkan. Pada saat build Config ketika pemasangan CssRenderingMode dan CssLayoutMode jatuh di luar sel kompatibel dari matriks mode. Satu-satunya pemasangan terlarang saat ini adalah CssRenderingMode::Safe + CssLayoutMode::Retained — Safe memaksa setiap fitur Phase 4+ nonaktif, sehingga konteks pemformatan mode-retained (Grid, Subgrid, @container) tidak memiliki konsumen, dan karenanya kombinasi tersebut ditolak alih-alih dibiarkan terdegradasi secara senyap. Memperluas StrictModeViolation.
• Konteks. getContext() menggabungkan bidang strict-mode induk dengan mode1 (nilai rendering-mode) dan mode2 (nilai layout-mode). cssDeviation mengkodekan pasangan mode tersebut; location adalah Config::validate().
• Pemulihan. Tindakan pemanggil-pustaka: pilih Safe + Streaming untuk rollback, atau mode rendering non-Safe (Normal / Strict / Audit) dengan Retained untuk Grid / Subgrid / Container Queries.

StrictModeViolation

• Kapan dilemparkan. Basis abstract untuk setiap eksepsi penyimpangan-spesifikasi yang dilemparkan di bawah CssRenderingMode::Strict. Dalam strict mode, setiap penyimpangan CSS yang terdeteksi dan tidak ditautkan ke entri eksepsi EXC-NNN terdaftar akan melemparkan instance dari kelas ini (atau subkelas) pada titik deteksi. Tidak dilemparkan secara langsung; lihat IncompatibleFeatureFlagsException dan IncompatibleRenderingModeException.
• Konteks. getContext() mengembalikan empat bidang ADR-023: cssDeviation (label singkat untuk konstruk yang menyimpang), excId (pengenal registri saat terdaftar, jika tidak null), chunkSha256 (hash chunk kutipan-spesifikasi saat diketahui, jika tidak null), dan location (asal yang dapat dibaca pemanggil, jika tidak null).
• Pemulihan. Tindakan pemanggil-pustaka: daftarkan penyimpangan tersebut sebagai entri EXC-NNN baru yang telah disetujui, atau perbaiki renderer untuk menghilangkan penyimpangan.

Masukan HTML dan CSS

HtmlParsingException

• Kapan dilemparkan. Ketika penguraian masukan HTML atau konstruksi DOM gagal: deklarasi charset tidak valid, pelanggaran batas-ukuran-masukan, kedalaman penyarangan berlebihan, overflow jumlah-elemen, dan kesalahan struktur-tabel seperti maksimum jumlah baris. Pengurasan sumber daya yang spesifik-CSS justru dilaporkan oleh CssParserLimitExceededException dan CssResolutionBudgetExceededException.
• Konteks. getContext() mengembalikan html_snippet (kutipan singkat yang dipangkas dari HTML yang bermasalah), position (offset byte, atau -1 jika tidak diketahui), dan rule (batasan parser yang dilanggar). Getter bertipe: getHtmlSnippet(), getPosition(), getRule().
• Pemulihan. Tindakan pengembang: sederhanakan masukan HTML atau sesuaikan batas parser.

CssParserLimitExceededException

• Kapan dilemparkan. Ketika masukan CSS melampaui batas keamanan parser yang dikonfigurasi. Dua kategori dicakup melalui konstruktor yang dinamai: forByteLimit() (stylesheet terlalu besar untuk pemrosesan regex yang aman) dan forNestingDepth() (rekursi penyarangan CSS terlalu dalam). Kedua pesan menyebutkan nilai aktual dan batasnya.
• Konteks. getContext() mengembalikan limit_type (byte atau nesting_depth), actual, dan limit.
• Pemulihan. Tindakan pengembang: pecah stylesheet menjadi lembar yang lebih kecil, atau kurangi kedalaman penyarangan, atau naikkan batas yang dikonfigurasi.

CssResolutionBudgetExceededException

• Kapan dilemparkan. Ketika resolusi CSS :has() melampaui anggaran penelusurannya. Resolver :has() dua-lintasan menegakkan anggaran kunjungan-node yang ketat untuk mencegah selektor patologis menyebabkan penelusuran dokumen kuadratik; setelah total jumlah kunjungan melampaui batas, stylesheet ditolak karena terlalu kompleks. Pesan tersebut menyebutkan jumlah kunjungan dan anggarannya.
• Konteks. getContext() mengembalikan visits dan budget. Getter bertipe: getVisits(), getBudget().
• Pemulihan. Tindakan pengembang: kurangi kompleksitas selektor, atau naikkan anggaran yang dikonfigurasi.

Font dan gambar

FontNotFoundException

• Kapan dilemparkan. Ketika berkas font tidak dapat ditemukan atau dibaca pada tingkat sistem berkas: keluarga atau jalur yang diminta tidak ada, tidak dapat dibaca, atau direktori font yang dikonfigurasi tidak dapat diakses. Data font mungkin valid — ini hanya menandakan bahwa data tersebut tidak dapat dijangkau. Pesan tersebut mencantumkan jalur yang dicari.
• Konteks. getContext() mengembalikan font_name, search_paths (sebuah daftar), dan fallback_attempted (sebuah bool). Getter bertipe: getFontName(), getSearchPaths(), wasFallbackAttempted().
• Pemulihan. Tindakan pengembang: verifikasi jalur font. Tindakan infrastruktur: perbaiki izin berkas pada berkas atau direktori font.

FontParsingException

• Kapan dilemparkan. Ketika berkas font ditemukan tetapi isinya tidak dapat digunakan: rusak, dalam format yang tidak didukung, atau kehilangan tabel wajib. Mencakup kegagalan validasi struktural selama penguraian TrueType, Type 1, CFF, dan OpenType — header terpotong, direktori tabel tidak valid, tabel wajib yang hilang (head, hhea, OS/2), kesalahan pembongkaran, dan pelanggaran ukuran. Pesan tersebut menyebutkan berkas dan kesalahan penguraian.
• Konteks. getContext() mengembalikan font_file dan parse_error. Getter bertipe: getFontFile(), getParseError().
• Pemulihan. Tindakan pengembang: ganti berkas font dengan berkas yang valid.

ImageProcessingException

• Kapan dilemparkan. Ketika sebuah gambar tidak dapat didekode, dalam format yang tidak didukung, atau gagal pemrosesan GD/Imagick: magic byte tak dikenal, data JPEG rusak, tipe MIME yang tidak didukung, pelanggaran batas-ukuran-berkas, dan kegagalan alokasi sumber daya GD. Gambar dapat diakses tetapi data pikselnya tidak dapat diekstraksi untuk penyematan.
• Konteks. getContext() mengembalikan image_path (kosong untuk data inline), format (yang terdeteksi atau diharapkan, mis. jpeg, png, unknown), dan operation (mis. decode, resize, embed). Getter bertipe: getImagePath(), getFormat(), getOperation().
• Pemulihan. Tindakan pengembang: suplai berkas gambar yang valid dan didukung.

Keluaran, tata letak, dan serialisasi

CompressionException

• Kapan dilemparkan. Ketika kompresi atau dekompresi FlateDecode (zlib) gagal — kegagalan gzcompress/gzuncompress pada content stream, data font, konten halaman, data lampiran, dan cross-reference stream. Biasanya berupa stream masukan yang rusak, memori tidak cukup, atau ekstensi zlib yang hilang.
• Konteks. getContext() mengembalikan algorithm (nama filter, mis. FlateDecode, LZWDecode) dan stream_length (panjang byte, atau -1 jika tidak diketahui). Getter bertipe: getAlgorithm(), getStreamLength().
• Pemulihan. Tindakan infrastruktur: verifikasi ext-zlib dimuat dan memori mencukupi.

WriterException

• Kapan dilemparkan. Ketika serialisasi PDF, linearisasi, atau keluaran I/O gagal: kesalahan penulisan-stream PdfWriter, korupsi tabel cross-reference, kegagalan pembuatan header/trailer, kegagalan resolusi referensi-objek, kesalahan penulisan berkas, dan overflow buffer-keluaran. Dokumen dalam-memori yang valid tidak dapat diserialisasi menjadi stream byte yang valid. Pesan tersebut menyebutkan tahapnya.
• Konteks. getContext() mengembalikan output_path (kosong untuk keluaran string) dan writer_state (tahap, mis. header, body, xref, trailer). Getter bertipe: getOutputPath(), getWriterState().
• Pemulihan. Tindakan infrastruktur: periksa ruang disk, izin berkas, dan stream keluaran.

PageLayoutException

• Kapan dilemparkan. Ketika batasan tata letak halaman tidak dapat dipenuhi: pelanggaran tata letak kolom (lebar tidak cukup, jumlah kolom tidak valid), overflow konten di luar batas halaman, dan konflik margin. Tata letak yang diminta secara geometris mustahil untuk dimensi halaman dan konten yang diberikan. Pesan tersebut menyebutkan nomor halaman saat diketahui dan batasan yang dilanggar.
• Konteks. getContext() mengembalikan page_number (berbasis-satu, atau 0 jika tidak diketahui) dan constraint. Getter bertipe: getPageNumber(), getConstraint().
• Pemulihan. Tindakan pengembang: sesuaikan ukuran halaman, margin, setelan kolom, atau konten.

TemplateException

• Kapan dilemparkan. Ketika operasi impor atau penggunaan ulang template PDF gagal di TemplateManager: transisi status template tidak valid (memulai atau mengakhiri template di luar urutan), mereferensikan template yang tidak ada, dan kegagalan kompresi stream selama serialisasi template. Pesan tersebut menyebutkan operasi dan id template saat ditetapkan.
• Konteks. getContext() mengembalikan template_id (kosong jika belum ditetapkan) dan operation (mis. begin, end, use, serialize). Getter bertipe: getTemplateId(), getOperation().
• Pemulihan. Tindakan pengembang: perbaiki urutan penggunaan template atau PDF sumbernya.

Invarian content-stream

ContentStreamBalanceException

• Kapan dilemparkan. Ketika ContentStreamBuilder mendeteksi pasangan operator yang tidak seimbang saat penutupan stream (atau di tengah stream ketika invarian ditegakkan secara dini). Eksepsi ini menangkap penghitung kedalaman yang gagal memenuhi invarian keseimbangan agar pencatatan log dapat mengidentifikasi emitter mana yang membocorkan q, BT, atau BMC tanpa pasangan Q, ET, atau EMC-nya. Sesuai ISO 32000-2:2020 §8.4.2 (tumpukan status-grafik), §9.4.1 (objek teks), dan §14.6 (marked content).
• Konteks. getContext() mengembalikan graphics_depth, text_block_depth, marked_content_depth, dan offending_operator. Getter bertipe: getGraphicsDepth(), getTextBlockDepth(), getMarkedContentDepth(), getOffendingOperator().
• Pemulihan. Tindakan pengembang: temukan emitter yang membuka sebuah konstruk tanpa menutupnya.

GraphicsStateBalanceException

• Kapan dilemparkan. Ketika sebuah PDF content stream ditutup dengan operator q/Q yang tidak seimbang. ISO 32000-2:2020 §8.4.2 mewajibkan setiap penyimpanan status-grafik (q) dipasangkan dengan tepat satu pemulihan (Q) sebelum stream berakhir; ketidakseimbangan membocorkan transform, clipping path, warna, dan rendering intent ke halaman berikutnya atau Form XObject. Dimunculkan hanya ketika pemeriksaan status-grafik ketat diaktifkan (NEXTPDF_GFXSTATE_STRICT=1); dalam mode relaksasi, peringatan dipancarkan melalui trigger_error() sebagai gantinya.
• Konteks. getContext() mengembalikan save_depth (positif untuk penyimpanan terlalu banyak, negatif untuk pemulihan terlalu banyak). Getter bertipe: getSaveDepth().
• Pemulihan. Tindakan pengembang: temukan pasangan save()/restore() yang tidak berpasangan.

MissingShadingResourceException

• Kapan dilemparkan. Ketika ConicGradientRenderer::render() dipanggil tanpa konteks registri Shading-resource. Perubahan yang memutus kompatibilitas pada v10.0.0 menghapus jalur surogat implicit-marker-map sebelumnya: pemanggil harus mengonstruksi renderer dengan ShadingResourceRegistryInterface agar objek tak langsung /ShadingType 4 terdaftar terhadap subdirektori Shading-resource halaman (ISO 32000-2 §8.7.4.2 / §8.7.4.3). Pesan tersebut menyebutkan konteks pemanggil dan menunjuk ke catatan migrasi v9.x→v10.0.
• Konteks. getContext() mengembalikan context (label konteks-pemanggil singkat, mis. ConicGradientRenderer::render).
• Pemulihan. Tindakan pemanggil-pustaka: pasangkan instance registri Shading-resource ke dalam konstruktor renderer sebelum memanggil render().

Linearisasi (Fast Web View)

LinearizationInvariantException

• Kapan dilemparkan. Ketika Linearizer tiga-lintasan v2 mendeteksi bahwa asersi MEASURE → PLACE → FILL miliknya dilanggar: jumlah byte Pass 3 yang tidak cocok dengan panjang berkas terprediksi Pass 1 (offset drift), placeholder kamus linearisasi yang terlalu kecil untuk lebar yang diserialisasi, atau offset hint-stream /H [offset length] yang tidak cocok dengan keluaran akhir. Memunculkan ini alih-alih memancarkan PDF yang rusak adalah jaminan keamanan yang dinyatakan.
• Konteks. getContext() mengembalikan invariant (nama invarian yang dilanggar), expected, actual, dan delta (selisih bertanda). Getter bertipe: getInvariant(), getExpectedValue(), getActualValue().
• Pemulihan. Tindakan pemelihara: ajukan laporan bug — invarian ini seharusnya berlaku untuk semua masukan yang terbentuk dengan baik. Tangkap eksepsi sebelumnya yang terangkai.

LinearizationUnimplementedException

• Kapan dilemparkan. Ketika feature flag linearizer disetel ke backend yang sengaja dinonaktifkan. Saat ini dimunculkan hanya untuk linearizerVersion === 'v1-noop', setelan penurunan-darurat yang menolak semua upaya linearisasi pada saat runtime tanpa perubahan kode atau redeploy — berguna untuk kill-switching Fast Web View di produksi.
• Konteks. getContext() mengembalikan reason (penjelasan singkat yang dapat dibaca manusia). Getter bertipe: getReason().
• Pemulihan. Tindakan operator / rekayasa-rilis: sesuaikan konfigurasi atau mutakhirkan ke versi backend yang diperbaiki.

Invarian konformansi dan profil

ConformanceViolationException

• Kapan dilemparkan. Ketika fitur yang diminta tidak dapat dipancarkan tanpa melanggar kontrak konformansi ISO yang dideklarasikan dokumen, dan mesin gagal-tertutup alih-alih menulis objek yang tidak konforman. Pemicu kanonisnya adalah anotasi multimedia Screen atau aksi Rendition (ISO 32000-2:2020 §12.5.6.18 / §13.2) di bawah profil arsip PDF/A, yang dilarang setiap bagian PDF/A (seri ISO 19005) — berkas tersebut akan gagal validasi veraPDF, sehingga mesin menolak sejak awal.
• Konteks. getContext() mengembalikan conformance_mode (mode yang dideklarasikan, mis. pdfa4) dan feature (fitur yang ditolak, mis. Screen annotation). Keduanya adalah properti readonly publik. Alasannya adalah pesan eksepsi.
• Pemulihan. Tindakan pengembang: hilangkan panggilan multimedia untuk keluaran arsip, atau targetkan profil konformansi non-arsip (bawaan ConformanceMode::Plain).

PdfRViolationException

• Kapan dilemparkan. Ketika invarian konformansi PDF/R-1 (ISO 23504-1:2020) dilanggar, baik pada konstruksi objek nilai (profil PdfRStrip, PdfRPage, PdfRDocument) maupun pada saat validator (PdfRValidator). Eksepsi ini menangkap klausul normatif yang bermasalah dan deskripsi pelanggaran satu baris sehingga konsumen audit dapat merutekan temuan ke sub-klausul §6 yang benar tanpa mengurai teks bebas.
• Konteks. getContext() mengembalikan standard (selalu ISO 23504-1:2020), clause (jalur klausul, mis. 6.6.1), dan violation. Getter bertipe: getClause(), getViolation().
• Pemulihan. Tindakan pengembang: perbaiki masukan yang ditolak atau bangun ulang dokumen agar konforman dengan klausul yang dikutip.

Pembuatan barcode

BarcodeException

• Kapan dilemparkan. Ketika pembuatan barcode gagal akibat data tidak valid atau kesalahan pengkodean di seluruh simbologi yang didukung (Code 39/128, UPC-A/E, EAN-8/13, Interleaved/Standard 2-of-5, POSTNET, PLANET, MSI, ISBN, ISSN, QR Code, PDF417, DataMatrix, JabCode), serta kegagalan rendering GD selama pembuatan gambar. Nilai barcode dibatasi-kutipan hingga 128 byte dalam pesan dan konteks — payload yang terlalu panjang atau biner disimpan terpangkas dengan penanda ... (<N> bytes, truncated) agar tidak dapat disalin utuh ke log.
• Konteks. getContext() mengembalikan barcode_type (simbologi, mis. QRCODE, EAN13, CODE128) dan value (nilai yang dipangkas). Getter bertipe: getBarcodeType(), getValue().
• Pemulihan. Tindakan pengembang: perbaiki data barcode atau pemilihan simbologi.

BarcodeEncoderNotFoundException

• Kapan dilemparkan. Dari BarcodeEncoderRegistry ketika tipe encoder yang diminta tidak dikenal atau gerbang kapabilitasnya tertutup. Eksepsi ini juga mengimplementasikan PSR-11 Psr\Container\NotFoundExceptionInterface, sehingga registri tersebut merupakan kontainer yang konforman-standar. Pesan tersebut menyebutkan simbologi dan alasannya.
• Konteks. Tidak menimpa getContext(), sehingga mengembalikan array kosong. type dan reason tersedia melalui getter getType() dan getReason() serta dalam pesan.
• Pemulihan. Tindakan pengembang: daftarkan encoder, atau pasang paket yang menyediakannya (misalnya nextpdf/pro untuk Micro QR / DotCode / HanXin / JabCode).

Kriptografi, enkripsi, dan tanda tangan

EncryptionException

• Kapan dilemparkan. Ketika enkripsi atau dekripsi PDF gagal: kegagalan enkripsi/dekripsi AES-256-CBC, kesalahan OpenSSL, ukuran IV tidak valid, kegagalan komputasi-hash, dan kesalahan komputasi-nilai UE/OE. Biasanya berupa ekstensi OpenSSL yang hilang atau salah konfigurasi, materi kunci tidak valid, atau data terenkripsi yang rusak. Pesan tersebut menyebutkan operasi dan algoritmenya.
• Konteks. getContext() mengembalikan algorithm (mis. AES-256-CBC) dan operation (mis. encrypt, decrypt, key_derivation). Getter bertipe: getAlgorithm(), getOperation().
• Pemulihan. Tindakan infrastruktur: pastikan OpenSSL tersedia dan terkonfigurasi dengan benar. Lihat Enkripsi dan izin.

UnsupportedAlgorithmException

• Kapan dilemparkan. Ketika algoritme kriptografi tidak dapat dieksekusi pada runtime saat ini: ekstensi PHP yang dibutuhkan tidak tersedia, pustaka pendukung tidak memiliki primitifnya, ekstensi hash bawaan tidak dapat mensintesis varian SHAKE/XOF, atau algoritme tidak terdaftar di SignatureAlgorithmRegistry. Mesin tidak boleh terdegradasi secara senyap ke primitif yang lebih lemah, sehingga mesin memunculkan ini. Factory statis nonFipsHostUnderFipsProfile() memunculkannya (dengan pengenal algoritme regulatory-profile:fips) ketika RegulatoryProfile::FIPS dipilih tetapi penyedia OpenSSL yang tervalidasi-FIPS tidak dapat dikonfirmasi (baik FIPS_ABSENT maupun INDETERMINATE gagal-tertutup).
• Konteks. getContext() mengembalikan algorithm (nama atau OID, mis. shake256, Ed25519, AES-256-GCM) dan reason (dapat ditindaklanjuti operator). Getter bertipe: getAlgorithm(), getReason().
• Pemulihan. Tindakan operator: pasang ekstensi yang hilang atau mutakhirkan runtime; untuk gerbang FIPS, pasang build OpenSSL yang tervalidasi-FIPS atau setel NEXTPDF_FIPS_MODE secara eksplisit. Tindakan pengembang: daftarkan deskriptor algoritme kustom melalui SignatureAlgorithmRegistry::register().

SignatureException

• Kapan dilemparkan. Ketika operasi tanda tangan digital gagal: penanganan sertifikat dan kunci privat (penguraian PKCS#12, pendekodean PEM/DER, validasi X.509), konstruksi PKCS#7/CMS, format tanda tangan ECDSA, pelanggaran ukuran-kontainer, pengkodean DER, dan orkestrasi PAdES. Kesalahan spesifik-TSA justru dilaporkan oleh TsaException yang lebih spesifik. Utamakan factory bertipe yang dinamai dibanding konstruktor posisional; masing-masing mengikat akar penyebab ke ekor pesan. Contoh: ltvCapabilityMissing() (B-LT/B-LTA membutuhkan nextpdf/enterprise), tsaRequired() / tsaUrlEmpty() / tsaEmptyToken(), httpClientMissing(), hsmSignerMissing() / hsmSignatureEmpty(), signatureContentsNotFound() / signatureContentsPaddingCorrupt(), unexpectedKeyType(), pemDecodingFailed(), keluarga Ed25519 (ed25519SignatureMalformed(), ed25519RoundTripVerifyFailed(), ed25519KeyParseFailed(), ed25519SeedInvalid(), ed25519SecretKeyMalformed(), ed25519PublicKeyInvalid()), documentTimestampNotEmitted(), algorithmPolicyRejected(), digestOnlyAlgorithmRefused(), encryptedLtvUnsupported(), incrementalUpdateWriterMissing(), serta pasangan status-OCSP nonSuccessfulOcspResponseStatus() / reservedOcspResponseStatus() (RFC 6960 §4.2.1). Factory ini gagal-tertutup alih-alih memancarkan tanda tangan yang diturunkan tingkatnya secara senyap.
• Konteks. getContext() mengembalikan cert_info (subjek DN atau thumbprint, atau kosong), signature_level (tingkat PAdES yang diupayakan, mis. B-B, B-T, B-LT, B-LTA), dan detail (diagnostik yang dapat ditindaklanjuti, kosong untuk konstruktor posisional lawas). Getter bertipe: getCertInfo(), getSignatureLevel(), getDetail().
• Pemulihan. Tindakan pengembang: perbaiki konfigurasi sertifikat/kunci. Untuk factory yang kekurangan kapabilitas, pasang paket yang disebut. Lihat Kegagalan tanda tangan dan stempel waktu untuk entri gejala-dan-solusi per factory.

BlackPointCompensationUnsupportedException

• Kapan dilemparkan. Dari NullBlackPointCompensationTransform::transform() ketika sebuah pemanggil meminta adaptor null untuk menerapkan transform kompensasi black-point ISO 18619 non-Default. Adaptor null adalah fallback aman untuk lingkungan tanpa backend manajemen-warna; menghasilkan sampel yang ditransformasi tanpa modul manajemen-warna sebenarnya akan salah melaporkan konversi secara senyap. Tidak seperti sebagian besar entri di sini, eksepsi ini memperluas \RuntimeException secara langsung, bukan NextPdfException, sehingga jalur catch (\RuntimeException) yang sudah ada tetap berfungsi.
• Konteks. Tidak ada getContext(); ini adalah \RuntimeException polos. Detailnya ada di pesan.
• Pemulihan. Tindakan pengembang: daftarkan sebuah BlackPointCompensationTransform sungguhan (LittleCMS, Argyll, PHP murni), atau batasi /UseBlackPtComp ke BlackPointCompensation::Default.

Perakitan dokumen dan aksesibilitas

UnsupportedSourceDocumentException

• Kapan dilemparkan. Ketika sebuah dokumen sumber tidak dapat disalin dengan aman ke keluaran merge/split dan operasinya gagal-tertutup alih-alih memancarkan hasil yang rusak atau terkompromi keamanan. Gunakan factory yang dinamai: encrypted() (ISO 32000-2 §7.6 — konten tidak dapat disalin tanpa kunci), signed() (§12.8 — menyalin halaman akan membatalkan rentang byte tanda tangan), unsupportedStreamFilter() (filter yang tidak dapat di-round-trip oleh reader graf-objek), multipleInteractiveForms() (batasan terdokumentasi: lebih dari satu sumber membawa /AcroForm non-kosong, §12.7), dan splitWithInteractiveForm() (batasan terdokumentasi: penyubsetan-halaman sumber bermuatan-form akan menelantarkan widget). Memperluas \RuntimeException secara langsung, bukan NextPdfException.
• Konteks. Tidak ada getContext(); ini adalah \RuntimeException polos. Penyebab dan nomor objek yang terdampak disebut dalam pesan.
• Pemulihan. Tindakan pengembang: dekripsi sumber terlebih dahulu atau suplai kuncinya; untuk sumber yang ditandatangani, tandatangani setelah merge; untuk merge multi-form, ratakan atau hapus bidang form dari semua sumber kecuali satu; untuk split bermuatan-form, ratakan form sebelum split.

InvalidBcp47TagException

• Kapan dilemparkan. Dari Bcp47Validator::validate() ketika sebuah kandidat tag bahasa cacat format menurut ABNF RFC 5646 §2.1, atau gagal dalam pencarian registri kuratif. Spesifik-domain untuk BCP-47 / ISO 14289-2:2024 §8.4.4, berbeda dari InvalidConfigException sehingga pemanggil di hilir batas aksesibilitas dapat menangkap tipe yang sempit. Pasangan predikat Bcp47Validator::isWellFormed() / isValid() tetap menjadi permukaan nilai-balik yang kompatibel-mundur untuk pemanggil yang lebih memilih bercabang daripada eksepsi.
• Konteks. getContext() mengembalikan tag (kandidat persis sebagaimana disuplai) dan reason (kode penolakan yang stabil dan dapat dibaca mesin, mis. empty-string, well-formed-shape, unregistered-primary, duplicate-variant). Getter bertipe: getTag(), getReason().
• Pemulihan. Tindakan pengembang: perbaiki tag bahasa menjadi tag BCP-47 yang terbentuk dengan baik dan terdaftar. Lihat Font dan tagging.

FormFieldAccessibilityException

• Kapan dilemparkan. Ketika sebuah bidang form interaktif akan bergantung pada nama aksesibel sintetis (bukan-disuplai-penulis) sementara menghasilkan dokumen PDF/UA dengan penegakan nama-bidang-aksesibel yang ketat diaktifkan. Keluaran PDF/UA bawaan memancarkan nama fallback sintetis ke /Contents widget agar sebuah bidang tidak pernah tanpa-nama; strict mode justru mewajibkan penulis menyuplai nama yang bermakna (sebuah tooltip, atau caption untuk push button tanpa-aksi) agar pengguna pembaca-layar mendapat deskripsi yang sebenarnya (ISO 14289-2:2024 §8.10.2).
• Konteks. Tidak menimpa getContext(), sehingga mengembalikan array kosong. $fieldId adalah properti readonly publik; alasannya adalah pesan.
• Pemulihan. Tindakan pengembang: suplai tooltip / nama aksesibel untuk bidang yang disebut sebelum menghasilkan dokumen PDF/UA ketat, atau nonaktifkan strict mode. Lihat Validasi PDF/A dan PDF/UA.

VendorExtensionRegistryConflictException

• Kapan dilemparkan. Dari VendorExtensionRegistry::register() ketika sebuah pemanggil mendaftarkan ulang prefiks vendor developer-extension PDF yang dikenal (ISO 32000-2:2020 §7.12.1) dengan deskripsi yang berbeda dari metadata yang sudah terdaftar. Deskriptor bersifat hanya-tambah dan terdeteksi-konflik; eksepsi bertipe ini menggantikan \RuntimeException generik agar pemanggil dapat menangkap kelas spesifik ini.
• Konteks. getContext() mengembalikan prefix, existing_description, dan attempted_description. Getter bertipe: getPrefix(), getExistingDescription(), getAttemptedDescription().
• Pemulihan. Tindakan pengembang: daftarkan prefiks dengan deskripsi yang sudah ada, atau gunakan prefiks yang berbeda; jangan menimpa metadata yang terdaftar.

Audit export

AuditExportException

• Kapan dilemparkan. Ketika perakitan bundel audit-export, pembuatan matriks-keterlacakan, atau proyeksi skema gagal pada saat runtime. Mencakup I/O terhadap claims.json / manifest.json, encode/decode JSON bundel kanonis, dan ketidakcocokan versi-skema pada jalur kompatibilitas-mundur AuditExporter::projectToV1(). Pesan tersebut menyebutkan tahap, artefak saat diketahui, dan detailnya.
• Konteks. getContext() mengembalikan stage (mis. read_claims, encode_bundle, project_v1), detail, dan artefact (jalur atau schema_version yang memicu kegagalan). Getter bertipe: getStage(), getDetail(), getArtefact().
• Pemulihan. Tindakan kepatuhan / DevOps: verifikasi jalur artefak masukan, hasilkan ulang claims.json dari proses yang bersih, atau bangun ulang manifest sebelum mencoba ekspor kembali.

Objek nilai pelanggaran

Ini bukan eksepsi. Ini adalah objek nilai yang tidak dapat diubah yang dikembalikan mesin untuk menggambarkan satu pelanggaran individual; keduanya tidak membawa getContext().

ComplianceViolation

• Apa ini. Objek nilai final readonly yang merepresentasikan satu kegagalan aturan yang dilaporkan oleh validator eksternal (veraPDF atau setara), termasuk referensi klausul ISO dan lokasinya dalam struktur PDF.
• Bidang. Properti readonly publik: ruleId (pengenal aturan validator, mis. 6.1.2-1), clause (referensi klausul ISO, mis. ISO 19005-1:2005, 6.1.2), severity (mis. error, warning), location (jalur objek dalam struktur PDF), dan message (deskripsi yang dapat dibaca manusia).
• Penggunaan. Periksa koleksi yang dikembalikan oleh validator kepatuhan; rutekan atau tampilkan setiap entri berdasarkan severity dan clause. Lihat Validasi PDF/A dan PDF/UA.

RuleViolation

• Apa ini. Objek nilai final readonly yang merepresentasikan satu pelanggaran aturan-bisnis Schematron / EN 16931, yang dikembalikan oleh SchematronRunnerInterface::runRules() dan diagregasikan di dalam ValidationResult::$ruleViolations. Stabilitasnya eksperimental.
• Bidang. Properti readonly publik: ruleId (pengenal EN 16931 seperti BR-{n}, BR-CO-{n}, BR-CL-{n}, BR-DEC-{n}, atau pack spesifik-tier), severity (sebuah enum RuleSeverity), message (teks aturan, en-GB), xpath (XPath ke dalam XML yang disematkan, null untuk aturan tingkat-dokumen), dan semanticPath (jalur BG/BT notasi-titik seperti BG-22.BT-106, null untuk pelanggaran struktural).
• Penggunaan. Periksa koleksi pada hasil validasi; rutekan atau tampilkan setiap entri berdasarkan severity, ruleId, dan pelokasinya.

Lihat juga

• Indeks referensi kesalahan
• Indeks basis pengetahuan
• Kegagalan tanda tangan dan stempel waktu
• Enkripsi dan izin
• Font dan tagging
• Validasi PDF/A dan PDF/UA