Справочник по ошибкам

Это справочный перечень исключений, которые генерирует NextPDF Core, сгруппированных по области. Каждая страница категории описывает по каждому классу, когда он генерируется, какие структурированные данные несёт и как восстановиться после сбоя. Если вы диагностируете симптом, а не перехватываете конкретный класс, начните вместо этого с руководств по устранению неполадок — они организованы по тому, что вы наблюдаете.

Краткий обзор

• Большинство исключений наследуются от единого базового класса NextPdfException, поэтому всё семейство можно перехватить одним блоком catch.
• NextPdfException является контекстно-зависимым: он реализует ContextAwareExceptionInterface, который объявляет getContext(): array. Многие подклассы переопределяют getContext(), чтобы вернуть структурированные диагностические ключи; другие наследуют пустую реализацию по умолчанию и раскрывают свои детали через сообщение и типизированные геттеры.
• Небольшое число низкоуровневых исключений наследуется напрямую от PHP-класса \RuntimeException, а не от NextPdfException. Они не являются контекстно-зависимыми и несут свои детали в публичных свойствах readonly. Каждая страница категории помечает их явно.
• Два типа соответствия с именами …Violation (ComplianceViolation, RuleViolation) являются объектами-значениями, а не исключениями — они описывают находку, не будучи сгенерированными.

Базовый тип и контракт контекста

NextPdfException — это абстрактный класс, который наследуется от \RuntimeException и реализует ContextAwareExceptionInterface. Контракт небольшой:

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

Поэтому защитный обработчик выглядит так:

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

Поскольку некоторые сбои проявляются как простое \RuntimeException (см. примечания по категориям), граница «с двойной защитой» может также перехватывать \RuntimeException и проверять конкретный тип.

Категории

• Основные и общие ошибки — сбои документа, слияния, доступности, электронных счетов, цветового пространства, объектов-значений и строгого режима, а также общие базовые типы.
• Ошибки безопасности, подписания и PKI — создание и проверка подписи, метки времени, проверка пути PKI и ограничений имён, хеширование, целостность и PKCS#11.
• Ошибки рендеринга и ввода-вывода — компоновка HTML и постраничный вывод, шрифты и формирование текста, писатель и читатель, а также метаданные XMP.
• Ошибки среды выполнения и поддержки — транспорт HTTP, отказоустойчивость (предохранитель, режим деградации), наблюдаемость и работа с манифестом.
• Ошибки Accelerator — транспорт опционального сопроводителя-ускорителя.
• Ошибки соответствия — требования к хешу пункта и жизненный цикл соответствия.

См. также

• Устранение неполадок — руководства, организованные по симптомам, для проверки подписи, шифрования и разрешений, шрифтов и тегирования, а также проверки PDF/A и PDF/UA.