База знаний по устранению неполадок

Что охватывает эта база знаний

Используйте эту базу знаний, чтобы связать наблюдаемый сбой с его причиной и способом устранения. Каждая запись опирается на собственные классы исключений движка, тесты путей сбоя и защитные проверки в исходном коде, а не на догадки. Если для конкретного сбоя в движке нет пути в коде, эта база знаний его не придумывает.

В базе знаний четыре тематические страницы:

• Проверка подписи — недействительные подписи, неполные цепочки, неизвестный статус отзыва и сбои меток времени.
• Проверка PDF/A и PDF/UA — проблемы Portable Document Format/Archive (PDF/A) и Portable Document Format/Universal Accessibility (PDF/UA), в том числе отсутствующий output intent, нетегированное содержимое, неуказанный язык и сбои внедрённых шрифтов.
• Шрифты и тегирование — ненайденные шрифты, создание подмножеств, покрытие CJK и проблемы дерева структуры.
• Шифрование и разрешения — сбои расшифровки и границы действия флагов разрешений.

Как читать запись

Каждая запись состоит из пяти частей:

1. Симптом — то, что вы видите: класс исключения, фрагмент сообщения или вердикт внешнего валидатора.
2. Вероятная причина — состояние входных данных или конфигурации, о котором сообщает движок.
3. Доказательство / диагностика — как подтвердить причину. Здесь указан точный класс исключения, поле getContext() или тест, демонстрирующий поведение, чтобы вы могли проверить причину, а не угадывать её.
4. Решение — последовательность шагов для устранения причины.
5. См. также — справочная страница модуля или смежная запись, которую стоит прочитать дальше.

Как определить сбой по типу исключения

NextPDF определяет ошибку по её PHP-классу, а не по строковому коду ошибки. В классах исключений нет константы NPDF-####. Перехватывайте конечное исключение, когда нужна точечная обработка, и читайте ContextAwareExceptionInterface::getContext(), чтобы получить структурированные диагностические поля. Как базовый тип используйте NextPDF\Exception\NextPdfException; сбои безопасности также используют NextPDF\Security\Exception\SecurityException.

Полную иерархию и правила порядка перехвата см. в справочнике по исключениям.

<?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.
}

Область применения и границы

Эта база знаний описывает, как движок обнаруживает сбои и сообщает о них. Она не разбирает вердикты соответствия внешних валидаторов, таких как veraPDF или callas; эти инструменты применяют собственные наборы правил. Когда движок отказывает в операции, чтобы удержать документ в рамках профиля, например, запрещает шифрование для PDF/A, соответствующая запись ссылается на нормативный пункт и исключение, которое обеспечивает это ограничение.

См. также

• Справочник по исключениям — полная иерархия, порядок перехвата и getContext() как контракт
• Справочник по соответствию — средства проверки профилей PDF/A, PDF/UA и PDF/X

Глоссарий: контекстно-зависимое исключение