Baza wiedzy dotycząca rozwiązywania problemów

Co obejmuje ta baza wiedzy

Skorzystaj z tej bazy wiedzy, aby powiązać napotkany błąd z jego przyczyną i sposobem rozwiązania. Każdy wpis opiera się na własnych klasach wyjątków silnika, testach ścieżek błędów i zabezpieczeniach w kodzie źródłowym, a nie na spekulacjach. Jeśli dla danego błędu silnik nie ma ścieżki kodu, baza wiedzy jej nie wymyśla.

Baza wiedzy zawiera cztery strony tematyczne:

• Walidacja podpisu — nieprawidłowe podpisy, niekompletne łańcuchy, nieznany status unieważnienia oraz błędy znaczników czasu.
• Walidacja PDF/A i PDF/UA — problemy z Portable Document Format/Archive (PDF/A) oraz Portable Document Format/Universal Accessibility (PDF/UA), w tym brak intencji wyjściowej, nieotagowana treść, brak języka i błędy osadzania czcionek.
• Czcionki i tagowanie — nieznaleziona czcionka, tworzenie podzbiorów, pokrycie CJK i problemy z drzewem struktury.
• Szyfrowanie i uprawnienia — błędy odszyfrowywania oraz granice flag uprawnień.

Jak czytać wpis

Każdy wpis ma pięć części:

1. Objaw — to, co widać: klasa wyjątku, fragment komunikatu lub werdykt walidatora pojawiający się później w procesie.
2. Prawdopodobna przyczyna — warunek danych wejściowych lub konfiguracji sygnalizowany przez silnik.
3. Dowody / diagnoza — sposób potwierdzenia przyczyny. Ta część wskazuje dokładną klasę wyjątku, pole getContext() lub test demonstrujący dane zachowanie, dzięki czemu można potwierdzić diagnozę zamiast zgadywać.
4. Rozwiązanie — uporządkowane kroki, które usuwają przyczynę.
5. Powiązane — strona referencyjna modułu lub pokrewny wpis do przeczytania w następnej kolejności.

Rozpoznawanie błędu według typu wyjątku

NextPDF identyfikuje błąd na podstawie jego klasy PHP, a nie tekstowego kodu błędu. W klasach wyjątków nie istnieje żadna stała NPDF-####. Przechwyć wyjątek liściowy, gdy potrzebna jest ukierunkowana reakcja, i odczytaj ContextAwareExceptionInterface::getContext(), aby uzyskać ustrukturyzowane pola diagnostyczne. Użyj NextPDF\Exception\NextPdfException jako typu bazowego; błędy bezpieczeństwa korzystają również z NextPDF\Security\Exception\SecurityException.

Aby poznać pełną hierarchię i reguły kolejności przechwytywania, przeczytaj dokumentację wyjątków.

<?php

declare(strict_types=1);

use NextPDF\Exception\NextPdfException;
use NextPDF\Contracts\ContextAwareExceptionInterface;

try {
    // ... engine call ...
} catch (NextPdfException $e) {
    $context = $e instanceof ContextAwareExceptionInterface
        ? $e->getContext()
        : [];
    \error_log($e->getMessage());
    // $context carries snake_case primitive fields safe to serialize.
}

Zakres i granice

Ta baza wiedzy opisuje, jak silnik wykrywa i zgłasza błędy. Nie obejmuje natomiast werdyktów zgodności wydawanych przez zewnętrzne walidatory, takie jak veraPDF czy callas; narzędzia te stosują własne zestawy reguł. Gdy silnik odmawia wykonania operacji, aby utrzymać dokument w obrębie profilu, na przykład odmawiając szyfrowania w PDF/A, odpowiedni wpis przytacza obowiązującą klauzulę oraz wyjątek, który ją egzekwuje.

Zobacz także

• Dokumentacja wyjątków — pełna hierarchia, kolejność przechwytywania i kontrakt getContext()
• Dokumentacja zgodności — narzędzia sprawdzające profile PDF/A, PDF/UA i PDF/X

Słowniczek: wyjątek z kontekstem