Kesalahan rendering dan I/O

Cakupan

Entri-entri ini mencakup eksepsi rendering dan input/output (I/O) yang dimunculkan saat pipeline HTML menata letak konten, resolver paged-media menetapkan geometri halaman, pembentuk teks memproses skrip kompleks, tahap tipografi memecah baris, writer menserialisasi dokumen, reader mengurai PDF yang sudah ada, dan tahap metadata membaca paket Extensible Metadata Platform (XMP).

Dua hierarki basis muncul di bawah, dan perbedaannya menentukan data diagnostik apa yang dapat Anda baca setelah sebuah catch:

• NextPdfException mengimplementasikan ContextAwareExceptionInterface::getContext(): array. Implementasi basis mengembalikan array kosong; sebuah subkelas membawa kunci terstruktur hanya ketika subkelas menimpa getContext(). Subkelas yang tidak menimpanya tetap memaparkan datanya melalui properti public readonly.
• Beberapa kelas di sini memperluas RuntimeException PHP secara langsung. Kelas-kelas tersebut tidak sadar-konteks dan tidak memiliki metode getContext(); baca getMessage()-nya dan properti publik mana pun sebagai gantinya.

Setiap entri menyebutkan kelas yang tepat, kondisi pemicu, kunci konteks atau properti publik yang dibawanya, dan jalur pemulihannya.

Tata letak HTML dan paged media

UnsplittableContentException

• Kapan dilemparkan. Mesin tata letak HTML memunculkan ini ketika konten yang ditandai break-inside: avoid (sebuah sel tabel yang batasan pemecahannya adalah Avoid) memiliki tinggi terukur yang melampaui tinggi yang dapat dipakai pada satu halaman. Mesin tidak dapat memenuhi baik batasan avoid-break maupun batas halaman, sehingga gagal alih-alih meluap secara senyap.
• Data yang dibawa. Memperluas NextPdfException tetapi tidak menimpa getContext(), sehingga getContext() mengembalikan array kosong. Data diagnostik ada pada properti public readonly: gridRow (int), gridCol (int), contentHeight (float, poin), dan pageHeight (float, poin). Pesan tersebut menyebutkan koordinat sel dan kedua tinggi.
• Pemulihan. Hapus batasan break-inside: avoid pada sel yang bermasalah, kurangi konten sel agar muat satu halaman, atau perbesar ukuran halaman atau kurangi marginnya agar tinggi yang dapat dipakai menampung konten.

BudgetExceededException

• Kapan dilemparkan. Primitif tata letak mode-retained memunculkan ini ketika salah satu dari empat tier anggaran-sumber-daya yang didefinisikan dalam architecture decision record ADR-020 dilanggar dan pemanggil memilih kegagalan keras alih-alih fallback lunak. Jalur bawaan tidak melempar: ContainerLayout::acceptChild() mengembalikan false, pemanggil jatuh kembali ke tata letak blok, dan sebuah peringatan dipancarkan. Eksepsi ini dicadangkan untuk validasi waktu-konfigurasi dan untuk tes yang mengasersi tuple pelanggaran yang persis. Tier-tier tersebut adalah per-child (sebuah stream anak yang ditangkap melampaui batasnya), per-container (anggaran jumlah-node Tier 1), per-document (anggaran lintasan-tata-letak atau kedalaman-penyarangan), dan global (plafon resident-set-size puncak 256 MB lebar-SDK).
• Data yang dibawa. Menimpa getContext(), yang mengembalikan bentuk delapan-kunci yang stabil dan dikonsumsi oleh perkakas application performance monitoring (APM): budgetTier, exceededValue, budgetLimit, containerType, phase, breachOrigin, captureSize, dan processedItemCount. Empat kunci pertama adalah subset v1.0.0 asli dan selalu terisi; empat kunci berikutnya default ke null atau 0 ketika konstruktor dipanggil tanpanya. getCausalWarningCode() memetakan tuple (tier, container-type) ke WarningCode yang akan dipancarkan jalur soft-fallback.
• Pemulihan. Untuk pelanggaran konfigurasi, turunkan nilai yang diminta kembali ke dalam amplop yang terdokumentasi (misalnya, anggaran node retained menerima 5.000 hingga 100.000 melalui Config::withRetainedNodeBudget()). Untuk pelanggaran konten, kurangi penyarangan kontainer atau jumlah node, atau andalkan soft-fallback bawaan ke tata letak blok alih-alih memilih permukaan kegagalan-keras.

UnsupportedNamedPageException

• Kapan dilemparkan. Tahap paged-media memunculkan ini, gagal-tertutup, ketika sebuah dokumen mendeklarasikan aturan @page <ident> { … } bernama (terikat ke konten melalui properti page: <ident>). Named page dari CSS Paged Media Level 3 §3.4 dan Level 4 §3.2 — termasuk pseudo-class :first, :left, :right, dan :blank serta override size: dan rotate: bernama — diurai tetapi tidak ada jalur tata letak produksi yang mengonsumsinya. Mesin menolak alih-alih memancarkan paginasi bawaan yang salah-secara-senyap yang akan dihasilkan jika aturan tersebut dibuang.
• Data yang dibawa. Menimpa getContext(), yang mengembalikan page_names (daftar ident berbeda yang memicu kegagalan, dalam urutan sumber), has_size_override (bool), has_rotate_override (bool), dan has_pseudo_classes (bool). Nilai-nilai yang sama dipaparkan pada properti publik pageNames, hasSizeOverride, hasRotateOverride, dan hasPseudoClasses.
• Pemulihan. Hapus aturan @page <ident> bernama dan setiap pengikatan page: <ident>, dan nyatakan geometri yang dimaksudkan melalui aturan @page { … } tanpa-nama yang didukung beserta bentuk pseudo-class-nya. Atau, pin ke rilis mendatang yang mendaratkan dukungan tata letak named-page penuh.

Tipografi dan pembentukan teks

IcuRequirementException

• Kapan dilemparkan. Segmentasi teks memunculkan ini ketika ia membutuhkan iterator line-break International Components for Unicode (ICU) tetapi kebijakan require-ICU aktif (NEXTPDF_REQUIRE_ICU=1) sementara ekstensi ext-intl dan IntlBreakIterator tidak tersedia.
• Data yang dibawa. Memperluas RuntimeException secara langsung, sehingga ia tidak sadar-konteks dan tidak memiliki getContext(). Ini adalah penyempurnaan ketat dari eksepsi generik yang sebelumnya dilemparkan jalur kode yang sama, sehingga penangan catch (\RuntimeException) yang sudah ada tetap berfungsi.
• Pemulihan. Pasang dan aktifkan ext-intl agar iterator break ICU tersedia, atau hapus pengaturan NEXTPDF_REQUIRE_ICU untuk jatuh kembali ke segmenter non-ICU di mana kebijakan require-ICU tidak wajib.

ScriptShaperException

• Kapan dilemparkan. Ini adalah eksepsi basis untuk service provider interface (SPI) script-shaping. Eksepsi ini tidak dilemparkan secara langsung saat ini; subtipe konkret dilemparkan sebagai gantinya. Tangkap tipe ini untuk menangani kegagalan pembentukan apa pun di satu tempat.
• Data yang dibawa. Memperluas RuntimeException secara langsung; tidak sadar-konteks, tidak ada getContext().
• Pemulihan. Bercabanglah pada subtipe konkret. Lihat NotYetImplementedException di bawah untuk satu-satunya subtipe yang disertakan dalam rilis saat ini.

NotYetImplementedException

• Kapan dilemparkan. Setiap script-shaper placeholder memunculkan ini dari badan shape()-nya untuk skrip yang pembentukan konkretnya ditangguhkan (Mongolia dan Tibet). Seam SPI pembentukan sudah siap secara arsitektural, tetapi pembentukan sebenarnya menunggu fixture yang tervalidasi-penutur-asli. Memunculkan eksepsi alih-alih no-op senyap mengungkap pengabelan produksi yang tak sengaja pada saat runtime alih-alih memancarkan teks tak-terbentuk ke dalam PDF yang mengeklaim aksesibilitas ber-tag.
• Data yang dibawa. Memperluas ScriptShaperException (dan karenanya RuntimeException), sehingga ia tidak sadar-konteks dan tidak memiliki getContext(). Data diagnostik ada pada properti public readonly-nya: bcp47LanguageTag (tag BCP-47 dari run, seperti mn-Mong atau bo-Tibt) dan missingCapability (kapabilitas konkret yang tidak dimiliki implementasi). Pesan tersebut menyertakan keduanya.
• Pemulihan. Jangan merutekan run dalam skrip yang belum diimplementasikan melalui shaper di produksi. Deteksi tag bahasa di hulu dan baik jatuh kembali ke jalur rendering yang berbeda atau pin ke rilis mendatang yang mendaratkan pembentukan untuk skrip yang terdampak.

Profil keluaran writer dan enkripsi

Pdf14FeatureRejectedException

• Kapan dilemparkan. Writer memunculkan ini ketika sebuah dokumen mengandung fitur yang dilarang di bawah profil keluaran PDF 1.4 (ISO 19005-1:2005 / PDF/A-1), yang melarang konstruk yang diperkenalkan pada versi PDF berikutnya.
• Data yang dibawa. Memperluas NextPdfException tetapi tidak menimpa getContext(), sehingga getContext() mengembalikan array kosong. Data diagnostik ada pada properti public readonly-nya: feature (nama fitur yang ditolak), reason (mengapa dilarang), dan isoClause (referensi klausul ISO). Pesan tersebut menggabungkan ketiganya.
• Pemulihan. Hapus atau ganti fitur yang ditolak dengan padanan yang kompatibel-PDF 1.4, atau targetkan profil keluaran yang lebih tinggi yang mengizinkan fitur tersebut.

Pdf20FeatureRejectedException

• Kapan dilemparkan. Writer memunculkan ini ketika sebuah dokumen mengandung fitur yang dilarang di bawah profil keluaran PDF 2.0 yang ketat. ISO 32000-2:2020 menghapus-usang konstruk yang masih diizinkan PDF 1.7 — paling utama font Type 1 Standard 14 (§9.6.2), yang harus disematkan dalam dokumen PDF 2.0 yang konforman.
• Data yang dibawa. Bentuk yang sama dengan Pdf14FeatureRejectedException: memperluas NextPdfException, tidak menimpa getContext() (mengembalikan array kosong), dan memaparkan feature, reason, dan isoClause sebagai properti public readonly.
• Pemulihan. Remediasi fitur yang ditolak — misalnya, sematkan base 14 font — atau ambil escape hatch terdokumentasi jika ada (untuk font base 14 yang tidak disematkan, Document::allowNonEmbeddedBase14()).

PublicKeyEncryptionUnsupportedException

• Kapan dilemparkan. PdfWriter::build() memunculkan ini pada titik masuk ketika encryptionMode dokumen adalah pubkey (sebuah daftar penerima public-key) sebelum dispatch enkripsi stream-body public-key sisi-writer terangkai. Menolak sejak awal mencegah pemancaran senyap sebuah PDF yang tidak terenkripsi yang diyakini pemanggil sebagai terenkripsi.
• Data yang dibawa. Memperluas RuntimeException secara langsung, sehingga ia tidak sadar-konteks dan tidak memiliki getContext(). Ini adalah penyempurnaan ketat dari eksepsi generik yang sebelumnya dilemparkan situs yang sama, sehingga penangan catch (\RuntimeException) yang sudah ada tetap berfungsi.
• Pemulihan. Gunakan mode enkripsi yang didukung (enkripsi berbasis-kata-sandi) alih-alih daftar penerima public-key, atau pin ke rilis yang mendaratkan dukungan enkripsi public-key. Jangan memperlakukan keluaran sebagai terenkripsi ketika ini dilemparkan.

Masukan reader dan metadata

UnsupportedPdfStructureException

• Kapan dilemparkan. Reader graf-objek memunculkan ini, gagal-tertutup, ketika sebuah PDF masukan jatuh di luar amplop yang didukungnya. Reader mendukung tabel cross-reference klasik (ISO 32000-2:2020 §7.5.4), cross-reference stream (§7.5.8), objek yang terkompresi-object-stream (§7.5.7), rantai /Prev multi-revisi (§7.5.6), dan berkas hybrid-reference melalui /XRefStm (§7.5.8.4). Segala hal di luar amplop tersebut memunculkan eksepsi ini alih-alih penguraian parsial atau tebakan. Konstruktor yang dinamai memetakan ke kasus alasan: encrypted(), damagedCrossReference(), cyclicReferenceChain(), nonConformantObjectStream(), irresolvableObjectCollision(), truncatedFile(), dan crossReferenceOffsetOutOfBounds().
• Data yang dibawa. Memperluas RuntimeException secara langsung, sehingga ia tidak sadar-konteks dan tidak memiliki getContext(). Eksepsi ini memaparkan properti public readonly reason bertipe UnsupportedPdfStructureReason (sebuah enum) sehingga pemanggil bercabang pada kategori yang presisi tanpa mengurai pesan; sebuah string detail opsional dan throwable previous dapat menambahkan konteks terbatas dan tak-sensitif. Pesan bawaan adalah ringkasan reason yang tidak membocorkan.
• Pemulihan. Bercabanglah pada reason. Untuk EncryptedDocument, jalankan langkah dekripsi sebelum membaca, karena dekripsi berada di luar cakupan reader. Untuk DamagedCrossReference, TruncatedFile, atau CrossReferenceOffsetOutOfBounds, perlakukan berkas sebagai cacat atau tidak lengkap dan peroleh ulang atau perbaiki sumbernya. Untuk CyclicReferenceChain, NonConformantObjectStream, atau IrresolvableObjectCollision, masukan melanggar model struktural dan tidak dapat dibaca apa adanya.

PacketTooLargeException

• Kapan dilemparkan. Pembaca metadata XMP streaming memunculkan ini ketika sebuah paket XMP yang disematkan melampaui plafon byte yang dikonfigurasi. Ini adalah penjaga defensif terhadap masukan bergaya entity-expansion dan quadratic-blowup (plafon puncak 128 MB terhadap XMP tersemat berskala-gigabyte).
• Data yang dibawa. Memperluas NextPdfException tetapi tidak menimpa getContext(), sehingga getContext() mengembalikan array kosong. Data diagnostik ada pada properti public readonly-nya: byteCount (jumlah byte teramati) dan cap (batas yang dikonfigurasi dalam byte). Pesan tersebut melaporkan keduanya.
• Pemulihan. Tolak atau lewati metadata berlebihan-ukuran sebagai jahat atau cacat. Jika sebuah dokumen yang sah benar-benar membutuhkan paket yang lebih besar, naikkan batas yang dikonfigurasi secara sengaja, dengan menimbang risiko memory-exhaustion yang menjadi alasan keberadaan penjaga tersebut.

Lihat juga

• Indeks referensi kesalahan
• Pemecahan masalah font dan tagging — untuk gejala NotYetImplementedException, ScriptShaperException, dan IcuRequirementException.
• Pemecahan masalah validasi PDF/A dan PDF/UA — untuk gejala Pdf14FeatureRejectedException dan Pdf20FeatureRejectedException.
• Pemecahan masalah enkripsi dan izin — untuk PublicKeyEncryptionUnsupportedException dan alasan EncryptedDocument reader.