Błędy core i ogólne

Zakres

Te wpisy obejmują podstawowe i ogólnego przeznaczenia wyjątki zgłaszane przez NextPDF. Większość rozszerza bazowy NextPdfException, który sam rozszerza \RuntimeException i implementuje ContextAwareExceptionInterface. Ten interfejs udostępnia jedną metodę, getContext(): array, zwracającą płaską mapę prymitywów w notacji snake_case, bezpieczną do serializacji w logu lub w ładunku APM.

Przechwytuj rodzinę NextPdfException jednym catch (NextPdfException $e). Dodaj również catch (\RuntimeException $e), aby objąć nieliczne niskopoziomowe błędy z tego zestawu, które rozszerzają \RuntimeException bezpośrednio (wymienione poniżej). Bazowa metoda NextPdfException::getContext() zwraca pustą tablicę; podklasy ją nadpisują, aby dodać pola domenowe. Tam, gdzie klasa nie nadpisuje getContext(), dziedziczy pustą tablicę, a szczegóły diagnostyczne znajdują się zamiast tego w komunikacie oraz w typowanych getterach.

Cztery typy w tym zestawie nie rozszerzają NextPdfException: BlackPointCompensationUnsupportedException oraz UnsupportedSourceDocumentException rozszerzają \RuntimeException bezpośrednio (przechwytuj je jako \RuntimeException), a ComplianceViolation oraz RuleViolation to obiekty wartości, a nie wyjątki — są tu udokumentowane, ponieważ modelują dane o błędach i naruszeniach, które zwraca silnik.

Wyjątek bazowy

NextPdfException

• Czym jest. Baza abstract dla głównej rodziny wyjątków NextPDF w obrębie rdzenia i jego pakietów rozszerzeń. Rozszerza \RuntimeException i implementuje ContextAwareExceptionInterface. Przechwycenie tego jednego typu przechwytuje rodzinę NextPdfException; nieliczne błędy, które rozszerzają \RuntimeException bezpośrednio (wymienione powyżej), wymagają również przechwycenia \RuntimeException.
• Kontekst. Bazowa getContext() zwraca pustą tablicę. Podklasy ją nadpisują, aby zwrócić pola właściwe dla domeny.
• Naprawa. Nie jest zgłaszany bezpośrednio. Użyj go jako typu przechwytującego wszystko; rozgałęziaj logikę według konkretnej podklasy w celu szczegółowej obsługi.

Konfiguracja i bramkowanie funkcji

InvalidConfigException

• Kiedy jest zgłaszany. Gdy wartość Config lub kombinacja wartości jest nieprawidłowa — brakuje wymaganego ustawienia, opcje wzajemnie się wykluczają lub wartość wykracza poza akceptowany zakres. Sygnalizuje to błąd programisty: kod wywołujący dostarczył konfigurację, którą trzeba poprawić przed ponowną próbą. Komunikat podaje klucz, oczekiwany typ lub zakres oraz rzeczywisty typ debugowy dostarczonej wartości.
• Kontekst. getContext() zwraca config_key, given_value oraz expected_type. Typowane gettery: getConfigKey(), getGivenValue(), getExpectedType().
• Naprawa. Działanie programisty: popraw nazwany klucz konfiguracyjny na wartość oczekiwanego typu lub zakresu przed kolejnym wywołaniem NextPDF.

NotImplementedException

• Kiedy jest zgłaszany. Gdy zostaje osiągnięty publiczny punkt wejścia API, ale jego implementacja jest celowo nieobecna w bieżącym wydaniu. Używany dla przejściowych nakładek (deprecated shims), które istnieją po to, by dać wywołującym sprzed bisekcji głośną, możliwą do obsłużenia awarię, a nie ciche działanie bez efektu. Komunikat łączy etykietę feature, którą można przeszukać maszynowo, z odwołaniem followUp (identyfikator usterki, kotwica śledzenia lub nazwa sprintu).
• Kontekst. Nie nadpisuje getContext(), więc zwraca pustą tablicę. Wartości $feature i $followUp to publiczne właściwości readonly osadzone w komunikacie.
• Naprawa. Działanie wywołującego bibliotekę: usuń wywołanie lub przypnij się do przyszłego wydania, które dostarczy nazwany element follow-up.

IncompatibleFeatureFlagsException

• Kiedy jest zgłaszany. W czasie budowania Config (Config::validate()), gdy kombinacja CssFeatureFlags jest wewnętrznie niespójna — jedna flaga zakłada inną, która jest wyłączona. Jedyna obecnie zabroniona kombinacja to layoutSubgrid = true z layoutGrid = false: oś subgrid wyprowadza swoje linie siatki z nadrzędnego kontenera siatki (CSS Grid Layout Module Level 2 §1), więc subgrid bez grid opisuje siatkę, która nie może istnieć. Sprawdzenie działa na rozwiązanych flagach, więc CssRenderingMode::Safe (który wymusza wyłączenie każdej funkcji z fazy 4+) maskuje tę kombinację, zamiast ją wyzwalać. Rozszerza StrictModeViolation.
• Kontekst. getContext() scala nadrzędne pola trybu ścisłego (cssDeviation, excId, chunkSha256, location) z wartościami logicznymi layoutGrid i layoutSubgrid. location to Config::validate(), a cssDeviation koduje parę flag.
• Naprawa. Działanie wywołującego bibliotekę: włącz layoutGrid razem z layoutSubgrid albo wyłącz layoutSubgrid.

IncompatibleRenderingModeException

• Kiedy jest zgłaszany. W czasie budowania Config, gdy para CssRenderingMode i CssLayoutMode znajduje się poza zgodnymi komórkami macierzy trybów. Jedyna obecnie zabroniona para to CssRenderingMode::Safe + CssLayoutMode::Retained — Safe wymusza wyłączenie każdej funkcji z fazy 4+, pozostawiając konteksty formatowania trybu retained (Grid, Subgrid, @container) bez konsumentów, więc ta kombinacja jest odrzucana, a nie cicho degradowana. Rozszerza StrictModeViolation.
• Kontekst. getContext() scala nadrzędne pola trybu ścisłego z mode1 (wartość trybu renderowania) i mode2 (wartość trybu układu). cssDeviation koduje parę trybów; location to Config::validate().
• Naprawa. Działanie wywołującego bibliotekę: wybierz Safe + Streaming do wycofania albo tryb renderowania inny niż Safe (Normal / Strict / Audit) z Retained dla Grid / Subgrid / Container Queries.

StrictModeViolation

• Kiedy jest zgłaszany. Baza abstract dla każdego wyjątku odchylenia od specyfikacji zgłaszanego w trybie CssRenderingMode::Strict. W trybie ścisłym każde wykryte odchylenie CSS niepowiązane z zarejestrowanym wpisem wyjątku EXC-NNN zgłasza instancję tej klasy (lub podklasy) w punkcie wykrycia. Nie jest zgłaszany bezpośrednio; zobacz IncompatibleFeatureFlagsException i IncompatibleRenderingModeException.
• Kontekst. getContext() zwraca cztery pola ADR-023: cssDeviation (krótka etykieta odbiegającej konstrukcji), excId (identyfikator rejestru, gdy zarejestrowany, w przeciwnym razie null), chunkSha256 (skrót fragmentu cytatu specyfikacji, gdy znany, w przeciwnym razie null) oraz location (czytelne dla wywołującego pochodzenie, w przeciwnym razie null).
• Naprawa. Działanie wywołującego bibliotekę: zarejestruj odchylenie jako nowy, zatwierdzony wpis EXC-NNN albo popraw mechanizm renderowania, aby usunąć odchylenie.

Dane wejściowe HTML i CSS

HtmlParsingException

• Kiedy jest zgłaszany. Gdy parsowanie danych wejściowych HTML lub budowanie DOM się nie powiedzie: nieprawidłowe deklaracje zestawu znaków, naruszenia limitu rozmiaru danych wejściowych, nadmierna głębokość zagnieżdżenia, przepełnienie liczby elementów oraz błędy struktury tabeli, takie jak maksimum liczby wierszy. Wyczerpanie zasobów właściwe dla CSS jest raportowane natomiast przez CssParserLimitExceededException oraz CssResolutionBudgetExceededException.
• Kontekst. getContext() zwraca html_snippet (krótki, przycięty fragment problematycznego HTML), position (przesunięcie w bajtach lub -1, jeśli nieznane) oraz rule (naruszone ograniczenie parsera). Typowane gettery: getHtmlSnippet(), getPosition(), getRule().
• Naprawa. Działanie programisty: uprość dane wejściowe HTML lub dostosuj limity parsera.

CssParserLimitExceededException

• Kiedy jest zgłaszany. Gdy dane wejściowe CSS przekraczają skonfigurowany limit bezpieczeństwa parsera. Dwie kategorie są obsługiwane przez nazwane konstruktory: forByteLimit() (arkusz stylów zbyt duży do bezpiecznego przetwarzania wyrażeniami regularnymi) oraz forNestingDepth() (rekurencja zagnieżdżenia CSS zbyt głęboka). Oba komunikaty podają wartość rzeczywistą i limit.
• Kontekst. getContext() zwraca limit_type (byte lub nesting_depth), actual oraz limit.
• Naprawa. Działanie programisty: podziel arkusz stylów na mniejsze arkusze, zmniejsz głębokość zagnieżdżenia albo podnieś skonfigurowany limit.

CssResolutionBudgetExceededException

• Kiedy jest zgłaszany. Gdy rozwiązywanie CSS :has() przekracza swój budżet przechodzenia. Dwuprzebiegowy resolver :has() egzekwuje ścisły budżet odwiedzin węzłów, aby zapobiec patologicznym selektorom powodującym kwadratowe przechodzenie dokumentu; gdy całkowita liczba odwiedzin przekroczy limit, arkusz stylów jest odrzucany jako zbyt złożony. Komunikat podaje liczbę odwiedzin oraz budżet.
• Kontekst. getContext() zwraca visits oraz budget. Typowane gettery: getVisits(), getBudget().
• Naprawa. Działanie programisty: zmniejsz złożoność selektorów albo podnieś skonfigurowany budżet.

Czcionki i obrazy

FontNotFoundException

• Kiedy jest zgłaszany. Gdy nie można zlokalizować ani odczytać pliku czcionki na poziomie systemu plików: żądana rodzina lub ścieżka nie istnieje, jest nieczytelna albo skonfigurowany katalog czcionek jest niedostępny. Dane czcionki mogą być prawidłowe — sygnalizuje to jedynie, że nie można ich osiągnąć. Komunikat wymienia przeszukane ścieżki.
• Kontekst. getContext() zwraca font_name, search_paths (listę) oraz fallback_attempted (wartość logiczną). Typowane gettery: getFontName(), getSearchPaths(), wasFallbackAttempted().
• Naprawa. Działanie programisty: zweryfikuj ścieżkę czcionki. Działanie infrastrukturalne: popraw uprawnienia do pliku lub katalogu czcionki.

FontParsingException

• Kiedy jest zgłaszany. Gdy plik czcionki zostaje odnaleziony, ale jego zawartość nie jest użyteczna: jest uszkodzony, w nieobsługiwanym formacie lub brakuje wymaganych tabel. Obejmuje awarie walidacji strukturalnej podczas parsowania TrueType, Type 1, CFF i OpenType — obcięte nagłówki, nieprawidłowe katalogi tabel, brakujące obowiązkowe tabele (head, hhea, OS/2), błędy rozpakowywania oraz naruszenia rozmiaru. Komunikat podaje plik oraz błąd parsowania.
• Kontekst. getContext() zwraca font_file oraz parse_error. Typowane gettery: getFontFile(), getParseError().
• Naprawa. Działanie programisty: zastąp plik czcionki prawidłowym.

ImageProcessingException

• Kiedy jest zgłaszany. Gdy nie można zdekodować obrazu, jest on w nieobsługiwanym formacie albo nie przechodzi przetwarzania GD/Imagick: nierozpoznawalne bajty magiczne, uszkodzone dane JPEG, nieobsługiwane typy MIME, naruszenia limitu rozmiaru pliku oraz awarie alokacji zasobów GD. Obraz był dostępny, ale jego danych pikseli nie udało się wyodrębnić do osadzenia.
• Kontekst. getContext() zwraca image_path (puste dla danych wbudowanych), format (wykryty lub oczekiwany, np. jpeg, png, unknown) oraz operation (np. decode, resize, embed). Typowane gettery: getImagePath(), getFormat(), getOperation().
• Naprawa. Działanie programisty: dostarcz prawidłowy, obsługiwany plik obrazu.

Wyjście, układ i serializacja

CompressionException

• Kiedy jest zgłaszany. Gdy kompresja lub dekompresja FlateDecode (zlib) się nie powiedzie — awarie gzcompress/gzuncompress na strumieniach treści, danych czcionek, treści strony, danych załączników oraz strumieniach odsyłaczy. Zwykle uszkodzony strumień wejściowy, niewystarczająca ilość pamięci lub brakujące rozszerzenie zlib.
• Kontekst. getContext() zwraca algorithm (nazwę filtra, np. FlateDecode, LZWDecode) oraz stream_length (długość w bajtach lub -1, jeśli nieznana). Typowane gettery: getAlgorithm(), getStreamLength().
• Naprawa. Działanie infrastrukturalne: zweryfikuj, że ext-zlib jest załadowane, a pamięci jest wystarczająco dużo.

WriterException

• Kiedy jest zgłaszany. Gdy serializacja PDF, linearyzacja lub wyjście wejścia/wyjścia się nie powiedzie: błędy zapisu strumienia PdfWriter, uszkodzenie tabeli odsyłaczy, awarie generowania nagłówka/zwiastuna, awarie rozwiązywania odwołań do obiektów, błędy zapisu plików oraz przepełnienia bufora wyjściowego. Prawidłowego dokumentu w pamięci nie udało się zserializować do prawidłowego strumienia bajtów. Komunikat podaje etap.
• Kontekst. getContext() zwraca output_path (puste dla wyjścia tekstowego) oraz writer_state (etap, np. header, body, xref, trailer). Typowane gettery: getOutputPath(), getWriterState().
• Naprawa. Działanie infrastrukturalne: sprawdź miejsce na dysku, uprawnienia do plików oraz strumień wyjściowy.

PageLayoutException

• Kiedy jest zgłaszany. Gdy nie można spełnić ograniczeń układu strony: naruszenia układu kolumnowego (niewystarczająca szerokość, nieprawidłowa liczba kolumn), przepełnienie treści poza granice strony oraz konflikty marginesów. Żądany układ jest geometrycznie niemożliwy dla danych wymiarów strony i danej treści. Komunikat podaje numer strony, gdy znany, oraz naruszone ograniczenie.
• Kontekst. getContext() zwraca page_number (liczone od jednego lub 0, jeśli nieznane) oraz constraint. Typowane gettery: getPageNumber(), getConstraint().
• Naprawa. Działanie programisty: dostosuj rozmiar strony, marginesy, ustawienia kolumn lub treść.

TemplateException

• Kiedy jest zgłaszany. Gdy operacja importu lub ponownego użycia szablonu PDF się nie powiedzie w TemplateManager: nieprawidłowe przejścia stanu szablonu (rozpoczynanie lub kończenie szablonów poza kolejnością), odwołanie do nieistniejącego szablonu oraz awarie kompresji strumienia podczas serializacji szablonu. Komunikat podaje operację oraz identyfikator szablonu, gdy został przypisany.
• Kontekst. getContext() zwraca template_id (puste, jeśli jeszcze nie przypisano) oraz operation (np. begin, end, use, serialize). Typowane gettery: getTemplateId(), getOperation().
• Naprawa. Działanie programisty: popraw sekwencję użycia szablonu lub źródłowy PDF.

Niezmienniki strumienia treści

ContentStreamBalanceException

• Kiedy jest zgłaszany. Gdy ContentStreamBuilder wykryje niezbalansowaną parę operatorów przy zamknięciu strumienia (lub w środku strumienia, gdy niezmienniki są asertowane zachłannie). Przechwytuje liczniki głębokości, które nie spełniły niezmiennika zbalansowania, aby logowanie mogło wskazać emiter, który pozostawił q, BT lub BMC bez dopasowanego Q, ET lub EMC. Zgodnie z ISO 32000-2:2020 §8.4.2 (stos stanu grafiki), §9.4.1 (obiekty tekstowe) oraz §14.6 (treść oznaczona).
• Kontekst. getContext() zwraca graphics_depth, text_block_depth, marked_content_depth oraz offending_operator. Typowane gettery: getGraphicsDepth(), getTextBlockDepth(), getMarkedContentDepth(), getOffendingOperator().
• Naprawa. Działanie programisty: zlokalizuj emiter, który otworzył konstrukcję bez jej zamknięcia.

GraphicsStateBalanceException

• Kiedy jest zgłaszany. Gdy strumień treści PDF zamyka się z niezbalansowanymi operatorami q/Q. ISO 32000-2:2020 §8.4.2 wymaga, aby każde zapisanie stanu grafiki (q) było dopasowane dokładnie jednym przywróceniem (Q) przed zakończeniem strumienia; brak równowagi przenosi transformację, ścieżkę przycinającą, barwy oraz intencję renderowania na kolejne strony lub obiekty Form XObject. Zgłaszany tylko wtedy, gdy włączone jest ścisłe sprawdzanie stanu grafiki (NEXTPDF_GFXSTATE_STRICT=1); w trybie złagodzonym zamiast tego emitowane jest ostrzeżenie przez trigger_error().
• Kontekst. getContext() zwraca save_depth (dodatnie przy zbyt wielu zapisach, ujemne przy zbyt wielu przywróceniach). Typowany getter: getSaveDepth().
• Naprawa. Działanie programisty: zlokalizuj niedopasowaną parę save()/restore().

MissingShadingResourceException

• Kiedy jest zgłaszany. Gdy ConicGradientRenderer::render() zostaje wywołany bez kontekstu rejestru zasobów Shading. Przełomowa zmiana w v10.0.0 usunęła wcześniejszą zastępczą ścieżkę z niejawną mapą znaczników: wywołujący muszą skonstruować mechanizm renderujący z ShadingResourceRegistryInterface, aby pośredni obiekt /ShadingType 4 został zarejestrowany w podsłowniku zasobów Shading strony (ISO 32000-2 §8.7.4.2 / §8.7.4.3). Komunikat podaje kontekst wywołującego i wskazuje notatkę migracji v9.x→v10.0.
• Kontekst. getContext() zwraca context (krótką etykietę kontekstu wywołującego, np. ConicGradientRenderer::render).
• Naprawa. Działanie wywołującego bibliotekę: podłącz instancję rejestru zasobów Shading do konstruktora mechanizmu renderującego przed wywołaniem render().

Linearyzacja (Fast Web View)

LinearizationInvariantException

• Kiedy jest zgłaszany. Gdy trójprzebiegowy Linearizer v2 wykryje naruszenie swoich asercji MEASURE → PLACE → FILL: liczba bajtów z przebiegu 3 niezgodna z przewidywaną w przebiegu 1 długością pliku (dryf przesunięcia), symbol zastępczy słownika linearyzacji zbyt mały dla zserializowanej szerokości albo przesunięcie strumienia podpowiedzi /H [offset length] niezgodne z ostatecznym wyjściem. Ujawnienie tego, zamiast wyemitowania uszkodzonego PDF, jest zadeklarowaną gwarancją bezpieczeństwa.
• Kontekst. getContext() zwraca invariant (nazwę naruszonego niezmiennika), expected, actual oraz delta (różnicę ze znakiem). Typowane gettery: getInvariant(), getExpectedValue(), getActualValue().
• Naprawa. Działanie opiekuna: zgłoś raport o błędzie — te niezmienniki powinny zachodzić dla wszystkich poprawnie sformowanych danych wejściowych. Zachowaj powiązany poprzedni wyjątek.

LinearizationUnimplementedException

• Kiedy jest zgłaszany. Gdy flaga funkcji linearyzatora jest ustawiona na backend, który jest celowo wyłączony. Obecnie zgłaszany tylko dla linearizerVersion === 'v1-noop', ustawienia awaryjnego obniżenia, które odrzuca wszystkie próby linearyzacji w czasie wykonania bez zmiany kodu ani ponownego wdrożenia — przydatne do awaryjnego wyłączania Fast Web View w produkcji.
• Kontekst. getContext() zwraca reason (krótkie, czytelne dla człowieka wyjaśnienie). Typowany getter: getReason().
• Naprawa. Działanie operatora / inżynierii wydania: dostosuj konfigurację albo zaktualizuj do naprawionej wersji backendu.

Niezmienniki zgodności i profilu

ConformanceViolationException

• Kiedy jest zgłaszany. Gdy żądanej funkcji nie można wyemitować bez złamania zadeklarowanego kontraktu zgodności ISO dokumentu, a silnik działa w trybie fail-closed, zamiast zapisać obiekt niezgodny. Kanonicznym wyzwalaczem jest multimedialna adnotacja Screen lub akcja Rendition (ISO 32000-2:2020 §12.5.6.18 / §13.2) w profilu archiwalnym PDF/A, czego zabrania każda część PDF/A (seria ISO 19005) — plik nie przeszedłby walidacji veraPDF, więc silnik odmawia z góry.
• Kontekst. getContext() zwraca conformance_mode (zadeklarowany tryb, np. pdfa4) oraz feature (odrzucona funkcja, np. Screen annotation). Obie to publiczne właściwości readonly. Przyczyna znajduje się w komunikacie wyjątku.
• Naprawa. Działanie programisty: usuń wywołanie multimediów dla wyjścia archiwalnego albo wybierz profil zgodności inny niż archiwalny (domyślnie ConformanceMode::Plain).

PdfRViolationException

• Kiedy jest zgłaszany. Gdy zostanie naruszony niezmiennik zgodności PDF/R-1 (ISO 23504-1:2020), czy to przy konstrukcji obiektu wartości (profile PdfRStrip, PdfRPage, PdfRDocument), czy w czasie walidacji (PdfRValidator). Przechwytuje problematyczną klauzulę normatywną oraz jednowierszowy opis naruszenia, aby konsumenci audytu mogli kierować ustalenia do właściwej podklauzuli §6 bez parsowania wolnego tekstu.
• Kontekst. getContext() zwraca standard (zawsze ISO 23504-1:2020), clause (ścieżkę klauzuli, np. 6.6.1) oraz violation. Typowane gettery: getClause(), getViolation().
• Naprawa. Działanie programisty: popraw odrzucone dane wejściowe lub przebuduj dokument, aby był zgodny z cytowaną klauzulą.

Generowanie kodów kreskowych

BarcodeException

• Kiedy jest zgłaszany. Gdy generowanie kodu kreskowego się nie powiedzie z powodu nieprawidłowych danych lub błędów kodowania we wszystkich obsługiwanych symbolikach (Code 39/128, UPC-A/E, EAN-8/13, Interleaved/Standard 2-of-5, POSTNET, PLANET, MSI, ISBN, ISSN, QR Code, PDF417, DataMatrix, JabCode) oraz awarii renderowania GD podczas tworzenia obrazu. Wartość kodu kreskowego jest przycinana do 128 bajtów w komunikacie i kontekście — zbyt długie lub binarne ładunki są przechowywane w postaci przyciętej ze znacznikiem ... (<N> bytes, truncated), aby nie dało się ich skopiować w całości do logu.
• Kontekst. getContext() zwraca barcode_type (symbolikę, np. QRCODE, EAN13, CODE128) oraz value (przyciętą wartość). Typowane gettery: getBarcodeType(), getValue().
• Naprawa. Działanie programisty: popraw dane kodu kreskowego lub wybór symboliki.

BarcodeEncoderNotFoundException

• Kiedy jest zgłaszany. Z BarcodeEncoderRegistry, gdy żądany typ kodera jest nieznany lub jego bramka możliwości jest zamknięta. Implementuje również PSR-11 Psr\Container\NotFoundExceptionInterface, więc rejestr jest kontenerem zgodnym ze standardem. Komunikat podaje symbolikę oraz przyczynę.
• Kontekst. Nie nadpisuje getContext(), więc zwraca pustą tablicę. type i reason są dostępne przez gettery getType() oraz getReason() i w komunikacie.
• Naprawa. Działanie programisty: zarejestruj koder albo zainstaluj pakiet, który go dostarcza (na przykład nextpdf/pro dla Micro QR / DotCode / HanXin / JabCode).

Kryptografia, szyfrowanie i podpisy

EncryptionException

• Kiedy jest zgłaszany. Gdy szyfrowanie lub odszyfrowywanie PDF się nie powiedzie: awarie szyfrowania/odszyfrowywania AES-256-CBC, błędy OpenSSL, nieprawidłowe rozmiary IV, awarie obliczania skrótu oraz błędy obliczania wartości UE/OE. Zwykle brakujące lub błędnie skonfigurowane rozszerzenie OpenSSL, nieprawidłowy materiał klucza albo uszkodzone zaszyfrowane dane. Komunikat podaje operację oraz algorytm.
• Kontekst. getContext() zwraca algorithm (np. AES-256-CBC) oraz operation (np. encrypt, decrypt, key_derivation). Typowane gettery: getAlgorithm(), getOperation().
• Naprawa. Działanie infrastrukturalne: upewnij się, że OpenSSL jest dostępne i poprawnie skonfigurowane. Zobacz Szyfrowanie i uprawnienia.

UnsupportedAlgorithmException

• Kiedy jest zgłaszany. Gdy algorytmu kryptograficznego nie można wykonać w bieżącym środowisku wykonawczym: wymagane rozszerzenie PHP jest niedostępne, bazowa biblioteka nie ma prymitywu, dołączone rozszerzenie hash nie potrafi zsyntetyzować wariantu SHAKE/XOF albo algorytm nie jest zarejestrowany w SignatureAlgorithmRegistry. Silnik nie może po cichu zdegradować do słabszego prymitywu, więc zamiast tego to ujawnia. Statyczna fabryka nonFipsHostUnderFipsProfile() zgłasza to (z identyfikatorem algorytmu regulatory-profile:fips), gdy wybrano RegulatoryProfile::FIPS, ale nie można potwierdzić walidowanego pod kątem FIPS dostawcy OpenSSL (zarówno FIPS_ABSENT, jak i INDETERMINATE działają w trybie fail-closed).
• Kontekst. getContext() zwraca algorithm (nazwę lub OID, np. shake256, Ed25519, AES-256-GCM) oraz reason (możliwy do obsłużenia przez operatora). Typowane gettery: getAlgorithm(), getReason().
• Naprawa. Działanie operatora: zainstaluj brakujące rozszerzenie lub zaktualizuj środowisko wykonawcze; dla bramki FIPS zainstaluj walidowaną pod kątem FIPS kompilację OpenSSL lub ustaw NEXTPDF_FIPS_MODE jawnie. Działanie programisty: zarejestruj niestandardowy deskryptor algorytmu przez SignatureAlgorithmRegistry::register().

SignatureException

• Kiedy jest zgłaszany. Gdy operacja podpisu cyfrowego się nie powiedzie: obsługa certyfikatu i klucza prywatnego (parsowanie PKCS#12, dekodowanie PEM/DER, walidacja X.509), budowanie PKCS#7/CMS, format podpisu ECDSA, naruszenia rozmiaru kontenera, kodowanie DER oraz orkiestracja PAdES. Błędy właściwe dla TSA są raportowane przez bardziej szczegółowy TsaException. Preferuj typowane nazwane fabryki zamiast konstruktora pozycyjnego; każda wiąże przyczynę źródłową z końcówką komunikatu. Przykłady: ltvCapabilityMissing() (B-LT/B-LTA wymaga nextpdf/enterprise), tsaRequired() / tsaUrlEmpty() / tsaEmptyToken(), httpClientMissing(), hsmSignerMissing() / hsmSignatureEmpty(), signatureContentsNotFound() / signatureContentsPaddingCorrupt(), unexpectedKeyType(), pemDecodingFailed(), rodzina Ed25519 (ed25519SignatureMalformed(), ed25519RoundTripVerifyFailed(), ed25519KeyParseFailed(), ed25519SeedInvalid(), ed25519SecretKeyMalformed(), ed25519PublicKeyInvalid()), documentTimestampNotEmitted(), algorithmPolicyRejected(), digestOnlyAlgorithmRefused(), encryptedLtvUnsupported(), incrementalUpdateWriterMissing() oraz para statusu OCSP nonSuccessfulOcspResponseStatus() / reservedOcspResponseStatus() (RFC 6960 §4.2.1). Te fabryki działają w trybie fail-closed, zamiast emitować po cichu obniżony podpis.
• Kontekst. getContext() zwraca cert_info (DN podmiotu lub odcisk palca albo puste), signature_level (poziom PAdES, którego dotyczyła próba, np. B-B, B-T, B-LT, B-LTA) oraz detail (możliwa do obsłużenia diagnoza, puste dla starego konstruktora pozycyjnego). Typowane gettery: getCertInfo(), getSignatureLevel(), getDetail().
• Naprawa. Działanie programisty: popraw konfigurację certyfikatu/klucza. Dla fabryk braku możliwości zainstaluj nazwany pakiet. Zobacz Błędy podpisu i znacznika czasu w celu uzyskania wpisów objaw-i-rozwiązanie dla poszczególnych fabryk.

BlackPointCompensationUnsupportedException

• Kiedy jest zgłaszany. Z NullBlackPointCompensationTransform::transform(), gdy wywołujący prosi adapter zerowy o zastosowanie innej niż Default transformacji kompensacji punktu czerni ISO 18619. Adapter zerowy jest bezpiecznym wariantem zapasowym dla środowisk bez backendu zarządzania barwą; wytworzenie przekształconej próbki bez prawdziwego modułu zarządzania barwą po cichu błędnie raportowałoby konwersję. W odróżnieniu od większości wpisów tutaj rozszerza on \RuntimeException bezpośrednio, a nie NextPdfException, więc istniejące ścieżki catch (\RuntimeException) nadal działają.
• Kontekst. Brak getContext(); to zwykły \RuntimeException. Szczegóły znajdują się w komunikacie.
• Naprawa. Działanie programisty: zarejestruj prawdziwą transformację BlackPointCompensationTransform (LittleCMS, Argyll, czysty PHP) albo ogranicz /UseBlackPtComp do BlackPointCompensation::Default.

Składanie dokumentów i dostępność

UnsupportedSourceDocumentException

• Kiedy jest zgłaszany. Gdy dokumentu źródłowego nie można bezpiecznie skopiować do wyjścia scalenia/podziału, a operacja działa w trybie fail-closed, zamiast wyemitować uszkodzony lub naruszony pod względem bezpieczeństwa wynik. Użyj nazwanych fabryk: encrypted() (ISO 32000-2 §7.6 — treści nie można skopiować bez klucza), signed() (§12.8 — skopiowanie stron unieważniłoby zakres bajtów podpisu), unsupportedStreamFilter() (filtr, którego czytnik grafu obiektów nie potrafi odtworzyć w obie strony), multipleInteractiveForms() (udokumentowane ograniczenie: więcej niż jedno źródło niesie niepusty /AcroForm, §12.7) oraz splitWithInteractiveForm() (udokumentowane ograniczenie: podzielenie na strony źródła z formularzem osierociłoby widżety). Rozszerza \RuntimeException bezpośrednio, a nie NextPdfException.
• Kontekst. Brak getContext(); to zwykły \RuntimeException. Przyczyna oraz numer dotkniętego obiektu są podane w komunikacie.
• Naprawa. Działanie programisty: najpierw odszyfruj źródło lub dostarcz klucz; dla źródeł podpisanych podpisz zamiast tego po scaleniu; dla scaleń z wieloma formularzami spłaszcz lub usuń pola formularza we wszystkich źródłach poza jednym; dla podziałów z formularzem spłaszcz formularz przed podziałem.

InvalidBcp47TagException

• Kiedy jest zgłaszany. Z Bcp47Validator::validate(), gdy kandydujący znacznik języka jest źle sformowany według ABNF z RFC 5646 §2.1 lub nie przechodzi wyszukiwania w wyselekcjonowanym rejestrze. Właściwy dla domeny BCP-47 / ISO 14289-2:2024 §8.4.4, odrębny od InvalidConfigException, aby wywołujący poniżej szwu dostępności mogli przechwycić wąski typ. Para predykatów Bcp47Validator::isWellFormed() / isValid() pozostaje zgodną wstecznie powierzchnią zwracającą wartość dla wywołujących, którzy wolą rozgałęzianie od wyjątków.
• Kontekst. getContext() zwraca tag (kandydata dokładnie tak, jak dostarczono) oraz reason (stabilny, czytelny maszynowo kod odrzucenia, np. empty-string, well-formed-shape, unregistered-primary, duplicate-variant). Typowane gettery: getTag(), getReason().
• Naprawa. Działanie programisty: popraw znacznik języka na poprawnie sformowany, zarejestrowany znacznik BCP-47. Zobacz Czcionki i tagowanie.

FormFieldAccessibilityException

• Kiedy jest zgłaszany. Gdy interaktywne pole formularza polegałoby na syntetycznej (niedostarczonej przez autora) nazwie dostępnej, podczas gdy tworzony jest dokument PDF/UA z włączonym ścisłym egzekwowaniem dostępnej nazwy pola. Domyślne wyjście PDF/UA emituje syntetyczną nazwę zapasową do /Contents widżetu, aby pole nigdy nie było bez nazwy; tryb ścisły zamiast tego wymaga, aby autor dostarczył sensowną nazwę (etykietkę narzędzia lub podpis dla przycisku bez akcji), tak aby użytkownicy czytników ekranu otrzymali prawdziwy opis (ISO 14289-2:2024 §8.10.2).
• Kontekst. Nie nadpisuje getContext(), więc zwraca pustą tablicę. $fieldId to publiczna właściwość readonly; przyczyna znajduje się w komunikacie.
• Naprawa. Działanie programisty: dostarcz etykietkę narzędzia / dostępną nazwę dla nazwanego pola przed utworzeniem ścisłego dokumentu PDF/UA albo wyłącz tryb ścisły. Zobacz Walidacja PDF/A i PDF/UA.

VendorExtensionRegistryConflictException

• Kiedy jest zgłaszany. Z VendorExtensionRegistry::register(), gdy wywołujący ponownie rejestruje znany prefiks dostawcy rozszerzenia programisty PDF (ISO 32000-2:2020 §7.12.1) z opisem niezgodnym z już zarejestrowanymi metadanymi. Deskryptory są tylko do dopisywania i wykrywają konflikty; typowany wyjątek zastąpił generyczny \RuntimeException, aby wywołujący mogli przechwytywać tę konkretną klasę.
• Kontekst. getContext() zwraca prefix, existing_description oraz attempted_description. Typowane gettery: getPrefix(), getExistingDescription(), getAttemptedDescription().
• Naprawa. Działanie programisty: zarejestruj prefiks z istniejącym opisem albo użyj odrębnego prefiksu; nie nadpisuj zarejestrowanych metadanych.

Eksport audytu

AuditExportException

• Kiedy jest zgłaszany. Gdy w czasie wykonania zawiedzie składanie pakietu eksportu audytu, generowanie macierzy śledzenia lub projekcja schematu. Obejmuje wejście/wyjście względem claims.json / manifest.json, kodowanie/dekodowanie JSON pakietu kanonicznego oraz niezgodność wersji schematu na zgodnej wstecznie ścieżce AuditExporter::projectToV1(). Komunikat podaje etap, artefakt, gdy znany, oraz szczegóły.
• Kontekst. getContext() zwraca stage (np. read_claims, encode_bundle, project_v1), detail oraz artefact (ścieżkę lub schema_version, która wyzwoliła awarię). Typowane gettery: getStage(), getDetail(), getArtefact().
• Naprawa. Działanie zgodności / DevOps: zweryfikuj ścieżki wejściowych artefaktów, wygeneruj claims.json ponownie z czystego przebiegu albo przebuduj manifest przed ponowną próbą eksportu.

Obiekty wartości naruszeń

To nie są wyjątki. To niezmienne obiekty wartości, które silnik zwraca, aby opisać pojedyncze naruszenie; nie niosą getContext().

ComplianceViolation

• Czym jest. Obiekt wartości final readonly reprezentujący jedno niespełnienie reguły zgłoszone przez zewnętrzny walidator (veraPDF lub równoważny), w tym odwołanie do klauzuli ISO oraz lokalizację w strukturze PDF.
• Pola. Publiczne właściwości readonly: ruleId (identyfikator reguły walidatora, np. 6.1.2-1), clause (odwołanie do klauzuli ISO, np. ISO 19005-1:2005, 6.1.2), severity (np. error, warning), location (ścieżka obiektu w strukturze PDF) oraz message (czytelny dla człowieka opis).
• Zastosowanie. Sprawdź kolekcję zwróconą przez walidator zgodności; kieruj lub wyświetlaj każdy wpis według severity i clause. Zobacz Walidacja PDF/A i PDF/UA.

RuleViolation

• Czym jest. Obiekt wartości final readonly reprezentujący jedno naruszenie reguły biznesowej Schematron / EN 16931, zwracane przez SchematronRunnerInterface::runRules() i agregowane wewnątrz ValidationResult::$ruleViolations. Stabilność jest eksperymentalna.
• Pola. Publiczne właściwości readonly: ruleId (identyfikator EN 16931, taki jak BR-{n}, BR-CO-{n}, BR-CL-{n}, BR-DEC-{n} lub pakiet właściwy dla poziomu), severity (wyliczenie RuleSeverity), message (tekst reguły, en-GB), xpath (XPath do osadzonego XML, null dla reguł obejmujących cały dokument) oraz semanticPath (ścieżka BG/BT w notacji kropkowej, taka jak BG-22.BT-106, null dla naruszeń strukturalnych).
• Zastosowanie. Sprawdź kolekcję w wyniku walidacji; kieruj lub wyświetlaj każdy wpis według severity, ruleId oraz lokalizatora.

Zobacz także

• Indeks dokumentacji błędów
• Indeks bazy wiedzy
• Błędy podpisu i znacznika czasu
• Szyfrowanie i uprawnienia
• Czcionki i tagowanie
• Walidacja PDF/A i PDF/UA