Błędy renderowania i wejścia/wyjścia

Zakres

Te wpisy obejmują wyjątki renderowania i wejścia/wyjścia (I/O) zgłaszane, gdy potok HTML rozmieszcza treść, resolver paged media przydziela geometrię stron, kształtowacz tekstu przetwarza złożone pisma, etap typografii dzieli wiersze, zapisywacz serializuje dokument, czytnik parsuje istniejący PDF, a etap metadanych odczytuje pakiet Extensible Metadata Platform (XMP).

Poniżej pojawiają się dwie hierarchie bazowe, a różnica między nimi rządzi tym, jakie dane diagnostyczne można odczytać po catch:

• NextPdfException implementuje ContextAwareExceptionInterface::getContext(): array. Implementacja bazowa zwraca pustą tablicę; podklasa niesie ustrukturyzowane klucze tylko wtedy, gdy nadpisuje getContext(). Podklasy, które jej nie nadpisują, nadal udostępniają swoje dane przez właściwości public readonly.
• Kilka klas tutaj rozszerza RuntimeException PHP bezpośrednio. Nie są one świadome kontekstu i nie mają metody getContext(); odczytaj ich getMessage() oraz wszelkie właściwości publiczne.

Każdy wpis podaje dokładną klasę, warunek wyzwalający, klucze kontekstu lub właściwości publiczne, które niesie, oraz ścieżkę naprawczą.

Układ HTML i paged media

UnsplittableContentException

• Kiedy jest zgłaszany. Silnik układu HTML zgłasza to, gdy treść oznaczona break-inside: avoid (komórka tabeli, której ograniczenie podziału to Avoid) ma zmierzoną wysokość przekraczającą użyteczną wysokość pojedynczej strony. Silnik nie może spełnić jednocześnie ograniczenia unikania podziału i granicy strony, więc zgłasza błąd zamiast po cichu przepełnić.
• Niesione dane. Rozszerza NextPdfException, ale nie nadpisuje getContext(), więc getContext() zwraca pustą tablicę. Dane diagnostyczne znajdują się we właściwościach public readonly: gridRow (int), gridCol (int), contentHeight (float, punkty) oraz pageHeight (float, punkty). Komunikat podaje współrzędne komórki oraz obie wysokości.
• Naprawa. Usuń ograniczenie break-inside: avoid na problematycznej komórce, zmniejsz treść komórki, aby zmieściła się na jednej stronie, albo zwiększ rozmiar strony lub zmniejsz jej marginesy, aby użyteczna wysokość pomieściła treść.

BudgetExceededException

• Kiedy jest zgłaszany. Prymitywy układu trybu retained zgłaszają to, gdy jeden z czterech poziomów budżetu zasobów zdefiniowanych w decyzji architektonicznej ADR-020 zostanie naruszony, a wywołujący zdecydował się na twardą awarię, a nie na miękki wariant zapasowy. Domyślna ścieżka nie zgłasza wyjątku: ContainerLayout::acceptChild() zwraca false, wywołujący cofa się do układu blokowego, a ostrzeżenie zostaje wyemitowane. Wyjątek jest zarezerwowany dla walidacji w czasie konfiguracji oraz dla testów, które asertują dokładną krotkę naruszenia. Poziomy to per-child (przechwycony strumień podrzędny przekracza swój pułap), per-container (budżet liczby węzłów Tier 1), per-document (budżet przebiegu układu lub głębokości zagnieżdżenia) oraz global (pułap szczytowego rezydentnego zbioru pamięci 256 MB obejmujący cały SDK).
• Niesione dane. Nadpisuje getContext(), który zwraca stabilny ośmioklucz kształt spożytkowany przez narzędzia monitorowania wydajności aplikacji (APM): budgetTier, exceededValue, budgetLimit, containerType, phase, breachOrigin, captureSize oraz processedItemCount. Pierwsze cztery klucze to oryginalny podzbiór z v1.0.0 i są zawsze wypełnione; ostatnie cztery domyślnie przyjmują null lub 0, gdy konstruktor zostanie wywołany bez nich. getCausalWarningCode() odwzorowuje krotkę (poziom, typ kontenera) na WarningCode, który wyemitowałaby ścieżka miękkiego wariantu zapasowego.
• Naprawa. W przypadku naruszenia konfiguracji obniż żądaną wartość z powrotem do udokumentowanej obwiedni (na przykład budżet węzłów retained akceptuje 5 000 do 100 000 przez Config::withRetainedNodeBudget()). W przypadku naruszenia treści zmniejsz zagnieżdżenie kontenerów lub liczbę węzłów albo zdaj się na domyślny miękki wariant zapasowy do układu blokowego zamiast decydować się na powierzchnię twardej awarii.

UnsupportedNamedPageException

• Kiedy jest zgłaszany. Etap paged media zgłasza to, w trybie fail-closed, gdy dokument deklaruje nazwaną regułę @page <ident> { … } (powiązaną z treścią przez właściwość page: <ident>). Nazwane strony z CSS Paged Media Level 3 §3.4 oraz Level 4 §3.2 — w tym pseudoklasy :first, :left, :right i :blank oraz nazwane przesłonięcia size: i rotate: — są parsowane, ale żadna produkcyjna ścieżka układu ich nie spożytkowuje. Silnik odmawia, zamiast wyemitować po cichu niepoprawną domyślną paginację, którą wytworzyłoby odrzucenie reguły.
• Niesione dane. Nadpisuje getContext(), który zwraca page_names (listę odrębnych identyfikatorów, które wyzwoliły awarię, w kolejności źródłowej), has_size_override (bool), has_rotate_override (bool) oraz has_pseudo_classes (bool). Te same wartości są udostępniane we właściwościach publicznych pageNames, hasSizeOverride, hasRotateOverride oraz hasPseudoClasses.
• Naprawa. Usuń nazwane reguły @page <ident> oraz wszelkie powiązania page: <ident> i wyraź zamierzoną geometrię przez obsługiwaną nienazwaną regułę @page { … } i jej formy pseudoklas. Alternatywnie przypnij się do przyszłego wydania, które dostarczy pełną obsługę układu nazwanych stron.

Typografia i kształtowanie tekstu

IcuRequirementException

• Kiedy jest zgłaszany. Segmentacja tekstu zgłasza to, gdy potrzebuje iteratora dzielenia wierszy International Components for Unicode (ICU), ale polityka require-ICU jest aktywna (NEXTPDF_REQUIRE_ICU=1), podczas gdy rozszerzenie ext-intl oraz IntlBreakIterator są niedostępne.
• Niesione dane. Rozszerza RuntimeException bezpośrednio, więc nie jest świadome kontekstu i nie ma getContext(). To ścisłe uściślenie generycznego wyjątku, który ta sama ścieżka kodu zgłaszała wcześniej, więc istniejące programy obsługi catch (\RuntimeException) nadal działają.
• Naprawa. Zainstaluj i włącz ext-intl, aby iterator dzielenia ICU był dostępny, albo usuń NEXTPDF_REQUIRE_ICU, aby cofnąć się do segmentatora bez ICU tam, gdzie polityka require-ICU nie jest obowiązkowa.

ScriptShaperException

• Kiedy jest zgłaszany. To wyjątek bazowy dla interfejsu dostawcy usług kształtowania pisma (SPI). Obecnie nie jest zgłaszany bezpośrednio; zamiast niego zgłaszane są konkretne podtypy. Przechwyć ten typ, aby obsłużyć każdą awarię kształtowania w jednym miejscu.
• Niesione dane. Rozszerza RuntimeException bezpośrednio; nie jest świadome kontekstu, brak getContext().
• Naprawa. Rozgałęziaj logikę na konkretny podtyp. Zobacz NotYetImplementedException poniżej w celu poznania jedynego podtypu dostarczanego w bieżącym wydaniu.

NotYetImplementedException

• Kiedy jest zgłaszany. Każdy zastępczy kształtowacz pisma zgłasza to z ciała swojej metody shape() dla pism, których konkretne kształtowanie jest odroczone (mongolskie i tybetańskie). Szew SPI kształtowania jest gotowy architektonicznie, ale rzeczywiste kształtowanie czeka na zwalidowaną przez rodzimego użytkownika fiksturę. Zgłoszenie wyjątku, a nie ciche działanie bez efektu, ujawnia przypadkowe produkcyjne podłączenie w czasie wykonania, zamiast wyemitować nieukształtowany tekst do PDF, który deklaruje otagowaną dostępność.
• Niesione dane. Rozszerza ScriptShaperException (a zatem RuntimeException), więc nie jest świadome kontekstu i nie ma getContext(). Dane diagnostyczne znajdują się w jego właściwościach public readonly: bcp47LanguageTag (znacznik BCP-47 przebiegu, taki jak mn-Mong lub bo-Tibt) oraz missingCapability (konkretna możliwość, której brakuje implementacji). Komunikat zawiera obie.
• Naprawa. Nie kieruj przebiegów w niezaimplementowanych pismach przez kształtowacz w produkcji. Wykryj znacznik języka wcześniej i albo cofnij się do innej ścieżki renderowania, albo przypnij się do przyszłego wydania, które dostarczy kształtowanie dla danego pisma.

Profile wyjściowe zapisywacza i szyfrowanie

Pdf14FeatureRejectedException

• Kiedy jest zgłaszany. Zapisywacz zgłasza to, gdy dokument zawiera funkcję zabronioną w profilu wyjściowym PDF 1.4 (ISO 19005-1:2005 / PDF/A-1), który zabrania konstrukcji wprowadzonych w późniejszych wersjach PDF.
• Niesione dane. Rozszerza NextPdfException, ale nie nadpisuje getContext(), więc getContext() zwraca pustą tablicę. Dane diagnostyczne znajdują się w jego właściwościach public readonly: feature (nazwa odrzuconej funkcji), reason (dlaczego jest zabroniona) oraz isoClause (odwołanie do klauzuli ISO). Komunikat łączy wszystkie trzy.
• Naprawa. Usuń lub zastąp odrzuconą funkcję odpowiednikiem zgodnym z PDF 1.4 albo wybierz wyższy profil wyjściowy, który dopuszcza tę funkcję.

Pdf20FeatureRejectedException

• Kiedy jest zgłaszany. Zapisywacz zgłasza to, gdy dokument zawiera funkcję zabronioną w ścisłym profilu wyjściowym PDF 2.0. ISO 32000-2:2020 wycofuje konstrukcje, które PDF 1.7 nadal dopuszczał — przede wszystkim czcionki Standard 14 Type 1 (§9.6.2), które w zgodnym dokumencie PDF 2.0 muszą być osadzone.
• Niesione dane. Ten sam kształt co Pdf14FeatureRejectedException: rozszerza NextPdfException, nie nadpisuje getContext() (zwraca pustą tablicę) i udostępnia feature, reason oraz isoClause jako właściwości public readonly.
• Naprawa. Napraw odrzuconą funkcję — na przykład osadź czcionki base 14 — albo skorzystaj z udokumentowanej furtki tam, gdzie istnieje (dla nieosadzonych czcionek base 14: Document::allowNonEmbeddedBase14()).

PublicKeyEncryptionUnsupportedException

• Kiedy jest zgłaszany. PdfWriter::build() zgłasza to w punkcie wejścia, gdy encryptionMode dokumentu to pubkey (lista odbiorców klucza publicznego), zanim dyspozytor szyfrowania ciała strumienia kluczem publicznym po stronie zapisywacza zostanie podłączony. Odmowa z góry zapobiega cichemu wyemitowaniu niezaszyfrowanego PDF, który wywołujący uważał za zaszyfrowany.
• Niesione dane. Rozszerza RuntimeException bezpośrednio, więc nie jest świadome kontekstu i nie ma getContext(). To ścisłe uściślenie generycznego wyjątku, który to samo miejsce zgłaszało wcześniej, więc istniejące programy obsługi catch (\RuntimeException) nadal działają.
• Naprawa. Użyj obsługiwanego trybu szyfrowania (szyfrowanie oparte na haśle) zamiast listy odbiorców klucza publicznego albo przypnij się do wydania, które dostarczy obsługę szyfrowania kluczem publicznym. Nie traktuj wyjścia jako zaszyfrowanego, gdy to zostanie zgłoszone.

Dane wejściowe czytnika i metadanych

UnsupportedPdfStructureException

• Kiedy jest zgłaszany. Czytnik grafu obiektów zgłasza to, w trybie fail-closed, gdy wejściowy PDF wykracza poza obsługiwaną obwiednię. Czytnik obsługuje klasyczne tabele odsyłaczy (ISO 32000-2:2020 §7.5.4), strumienie odsyłaczy (§7.5.8), obiekty skompresowane w strumieniach obiektów (§7.5.7), wielorewizyjne łańcuchy /Prev (§7.5.6) oraz pliki o hybrydowych odsyłaczach przez /XRefStm (§7.5.8.4). Wszystko poza tą obwiednią ujawnia ten wyjątek, a nie częściowy lub zgadywany parse. Nazwane konstruktory odwzorowują się na przypadki przyczyn: encrypted(), damagedCrossReference(), cyclicReferenceChain(), nonConformantObjectStream(), irresolvableObjectCollision(), truncatedFile() oraz crossReferenceOffsetOutOfBounds().
• Niesione dane. Rozszerza RuntimeException bezpośrednio, więc nie jest świadome kontekstu i nie ma getContext(). Udostępnia właściwość public readonly reason typu UnsupportedPdfStructureReason (wyliczenie), aby wywołujący rozgałęziali logikę na precyzyjnej kategorii bez parsowania komunikatu; opcjonalny napis detail oraz previous throwable mogą dodać ograniczony, niewrażliwy kontekst. Domyślny komunikat to niewyciekające podsumowanie przyczyny.
• Naprawa. Rozgałęziaj logikę na reason. Dla EncryptedDocument wykonaj krok odszyfrowania przed odczytem, ponieważ odszyfrowywanie jest poza zakresem czytnika. Dla DamagedCrossReference, TruncatedFile lub CrossReferenceOffsetOutOfBounds potraktuj plik jako źle sformowany lub niekompletny i pobierz ponownie lub napraw źródło. Dla CyclicReferenceChain, NonConformantObjectStream lub IrresolvableObjectCollision dane wejściowe naruszają model strukturalny i nie da się ich odczytać w obecnej postaci.

PacketTooLargeException

• Kiedy jest zgłaszany. Strumieniowy czytnik metadanych XMP zgłasza to, gdy osadzony pakiet XMP przekracza skonfigurowany pułap bajtów. To defensywne zabezpieczenie przed danymi wejściowymi typu rozszerzania encji i kwadratowego rozrostu (pułap szczytowy 128 MB wobec osadzonego XMP o skali gigabajtów).
• Niesione dane. Rozszerza NextPdfException, ale nie nadpisuje getContext(), więc getContext() zwraca pustą tablicę. Dane diagnostyczne znajdują się w jego właściwościach public readonly: byteCount (zaobserwowana liczba bajtów) oraz cap (skonfigurowany pułap w bajtach). Komunikat raportuje oba.
• Naprawa. Odrzuć lub pomiń przewymiarowane metadane jako złośliwe lub źle sformowane. Jeśli zasadny dokument faktycznie potrzebuje większego pakietu, podnieś skonfigurowany pułap z rozmysłem, ważąc ryzyko wyczerpania pamięci, któremu zabezpieczenie ma zapobiegać.

Zobacz także

• Indeks dokumentacji błędów
• Rozwiązywanie problemów z czcionkami i tagowaniem — w przypadku objawów NotYetImplementedException, ScriptShaperException oraz IcuRequirementException.
• Rozwiązywanie problemów z walidacją PDF/A i PDF/UA — w przypadku objawów Pdf14FeatureRejectedException oraz Pdf20FeatureRejectedException.
• Rozwiązywanie problemów z szyfrowaniem i uprawnieniami — w przypadku PublicKeyEncryptionUnsupportedException oraz przyczyny EncryptedDocument czytnika.