Dokumentacja błędów

To jest referencyjna lista wyjątków zgłaszanych przez NextPDF Core, uporządkowana według obszaru. Każda strona kategorii dokumentuje, dla każdej klasy, kiedy jest zgłaszana, jakie ustrukturyzowane dane niesie oraz jak naprawić sytuację. Jeśli diagnozujesz objaw, a nie przechwytujesz konkretną klasę, zacznij raczej od przewodników rozwiązywania problemów — są one uporządkowane według tego, co obserwujesz.

W skrócie

• Większość wyjątków rozszerza jedną bazę, NextPdfException, więc całą rodzinę można przechwycić jednym blokiem catch.
• NextPdfException jest świadoma kontekstu: implementuje ContextAwareExceptionInterface, który deklaruje getContext(): array. Wiele podklas nadpisuje getContext(), aby zwrócić ustrukturyzowane klucze diagnostyczne; inne dziedziczą pustą wartość domyślną i udostępniają szczegóły przez komunikat oraz typowane gettery.
• Niewielka liczba niskopoziomowych wyjątków rozszerza bezpośrednio \RuntimeException PHP, a nie NextPdfException. Nie są one świadome kontekstu i niosą szczegóły w publicznych właściwościach readonly. Każda strona kategorii oznacza je wyraźnie.
• Dwa typy zgodności o nazwie zakończonej na …Violation (ComplianceViolation, RuleViolation) to obiekty wartości, a nie wyjątki — opisują ustalenie, nie będąc zgłaszane.

Typ bazowy i kontrakt kontekstu

NextPdfException to klasa abstrakcyjna, która rozszerza \RuntimeException i implementuje ContextAwareExceptionInterface. Kontrakt jest niewielki:

interface ContextAwareExceptionInterface
{
    /** @return array<string, mixed> structured, log-safe diagnostic context */
    public function getContext(): array;
}

Defensywny program obsługi wygląda zatem tak:

use NextPDF\Exception\NextPdfException;

try {
    // … NextPDF operation …
} catch (NextPdfException $e) {
    $logger->error($e->getMessage(), $e->getContext());
    // getContext() returns [] when a subclass does not override it;
    // the message and any typed getters still carry the detail.
}

Ponieważ niektóre awarie ujawniają się jako goły \RuntimeException (zobacz uwagi przy poszczególnych kategoriach), granica zabezpieczona „pasem i szelkami” może dodatkowo przechwytywać \RuntimeException i sprawdzać konkretny typ.

Kategorie

• Błędy core i ogólne — awarie dokumentu, scalania, dostępności, e-faktury, przestrzeni barw, obiektów wartości oraz trybu ścisłego, a także współdzielone typy bazowe.
• Błędy bezpieczeństwa, podpisywania i PKI — tworzenie i weryfikacja podpisu, znaczniki czasu, walidacja ścieżki PKI i ograniczeń nazw, haszowanie, integralność oraz PKCS#11.
• Błędy renderowania i wejścia/wyjścia — układ HTML i paged media, czcionki i kształtowanie tekstu, zapisywanie i odczyt oraz metadane XMP.
• Błędy środowiska wykonawczego i wsparcia — transport HTTP, odporność (wyłącznik obwodu, tryb zdegradowany), obserwowalność oraz obsługa manifestu.
• Błędy akceleratora — transport opcjonalnego pomocniczego procesu akceleracji (sidecar).
• Błędy zgodności — wymagania dotyczące skrótu klauzuli oraz cykl życia zgodności.

Zobacz także

• Rozwiązywanie problemów — przewodniki uporządkowane według objawów dla walidacji podpisu, szyfrowania i uprawnień, czcionek i tagowania oraz walidacji PDF/A i PDF/UA.