Основные и общие ошибки

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

Эти записи охватывают основные и общего назначения исключения, которые генерирует NextPDF. Большинство наследуются от базового NextPdfException, который сам наследуется от \RuntimeException и реализует ContextAwareExceptionInterface. Этот интерфейс предоставляет один метод, getContext(): array, возвращающий плоское отображение в стиле snake_case из примитивов, безопасных для сериализации в журнал или полезную нагрузку APM.

Перехватывайте семейство NextPdfException одним блоком catch (NextPdfException $e). Добавьте также catch (\RuntimeException $e), чтобы охватить те немногие низкоуровневые ошибки в этом наборе, которые наследуются напрямую от \RuntimeException (перечислены ниже). Базовый NextPdfException::getContext() возвращает пустой массив; подклассы переопределяют его, чтобы добавить доменные поля. Там, где класс не переопределяет getContext(), он наследует пустой массив, а диагностические детали находятся вместо этого в сообщении и типизированных геттерах.

Четыре типа в этом наборе не наследуются от NextPdfException: BlackPointCompensationUnsupportedException и UnsupportedSourceDocumentException наследуются напрямую от \RuntimeException (перехватывайте их как \RuntimeException), а ComplianceViolation и RuleViolation являются объектами-значениями, а не исключениями — они описаны здесь, потому что моделируют данные об ошибках и нарушениях, которые возвращает движок.

Базовое исключение

NextPdfException

• Что это. abstract базовый класс для каждого исключения, генерируемого ядром NextPDF и его пакетами расширений. Он наследуется от \RuntimeException и реализует ContextAwareExceptionInterface. Перехват этого единственного типа перехватывает любую ошибку библиотеки.
• Контекст. Базовый getContext() возвращает пустой массив. Подклассы переопределяют его, чтобы вернуть доменно-специфичные поля.
• Восстановление. Не генерируется напрямую. Используйте его как тип-перехватчик всего; ветвитесь по конкретному подклассу для специфической обработки.

Конфигурация и гейтинг возможностей

InvalidConfigException

• Когда генерируется. Когда значение Config или сочетание значений недопустимо — отсутствует обязательная настройка, заданы взаимоисключающие опции или значение выходит за пределы допустимого диапазона. Это сигнализирует об ошибке разработчика: вызывающий код передал конфигурацию, которую нужно исправить перед повторной попыткой. Сообщение указывает ключ, ожидаемый тип или диапазон, а также фактический отладочный тип переданного значения.
• Контекст. getContext() возвращает config_key, given_value и expected_type. Типизированные геттеры: getConfigKey(), getGivenValue(), getExpectedType().
• Восстановление. Действие разработчика: исправьте указанный ключ конфигурации на значение ожидаемого типа или диапазона перед повторным вызовом NextPDF.

NotImplementedException

• Когда генерируется. Когда достигнута публичная точка входа API, но её реализация намеренно отсутствует в текущем релизе. Используется для устаревших заглушек, которые существуют, чтобы дать вызывающим до bisect громкий, действенный сбой, а не молчаливое отсутствие операции. Сообщение объединяет пригодную для grep-поиска метку feature и ссылку followUp (идентификатор дефекта, якорь отслеживания или имя спринта).
• Контекст. Не переопределяет getContext(), поэтому возвращает пустой массив. Значения $feature и $followUp являются публичными свойствами readonly и встроены в сообщение.
• Восстановление. Действие вызывающей стороны библиотеки: удалите вызов или закрепитесь на будущем релизе, в котором появится названный follow-up.

IncompatibleFeatureFlagsException

• Когда генерируется. На этапе сборки Config (Config::validate()), когда сочетание CssFeatureFlags внутренне несогласованно — один флаг предполагает другой, который отключён. Единственное запрещённое сегодня сочетание — layoutSubgrid = true при layoutGrid = false: подсетка по оси выводит свои линии сетки из родительского контейнера сетки (CSS Grid Layout Module Level 2 §1), поэтому subgrid без grid описывает сетку, которая не может существовать. Проверка выполняется на разрешённых флагах, поэтому CssRenderingMode::Safe (который принудительно отключает каждую возможность Phase 4+) маскирует это сочетание, а не приводит к его срабатыванию. Наследуется от StrictModeViolation.
• Контекст. getContext() объединяет родительские поля строгого режима (cssDeviation, excId, chunkSha256, location) с булевыми значениями layoutGrid и layoutSubgrid. location — это Config::validate(), а cssDeviation кодирует пару флагов.
• Восстановление. Действие вызывающей стороны библиотеки: включите layoutGrid вместе с layoutSubgrid или отключите layoutSubgrid.

IncompatibleRenderingModeException

• Когда генерируется. На этапе сборки Config, когда сочетание CssRenderingMode и CssLayoutMode выходит за пределы совместимых ячеек матрицы режимов. Единственное запрещённое сегодня сочетание — CssRenderingMode::Safe + CssLayoutMode::Retained — Safe принудительно отключает каждую возможность Phase 4+, оставляя контексты форматирования удерживаемого режима (Grid, Subgrid, @container) без потребителей, поэтому сочетание отклоняется, а не позволяет молча деградировать. Наследуется от StrictModeViolation.
• Контекст. getContext() объединяет родительские поля строгого режима с mode1 (значение режима рендеринга) и mode2 (значение режима компоновки). Поле cssDeviation кодирует пару режимов; location — это Config::validate().
• Восстановление. Действие вызывающей стороны библиотеки: выберите Safe + Streaming для отката или режим рендеринга, отличный от Safe (Normal / Strict / Audit), с Retained для Grid / Subgrid / Container Queries.

StrictModeViolation

• Когда генерируется. abstract базовый класс для любого исключения об отклонении от спецификации, генерируемого под CssRenderingMode::Strict. В строгом режиме любое обнаруженное отклонение CSS, не связанное с зарегистрированной записью исключения EXC-NNN, генерирует экземпляр этого класса (или подкласса) в точке обнаружения. Не генерируется напрямую; см. IncompatibleFeatureFlagsException и IncompatibleRenderingModeException.
• Контекст. getContext() возвращает четыре поля ADR-023: cssDeviation (краткая метка для отклоняющейся конструкции), excId (идентификатор реестра, если он зарегистрирован, иначе null), chunkSha256 (хеш фрагмента спецификации-ссылки, если он известен, иначе null) и location (читаемое для вызывающей стороны происхождение, иначе null).
• Восстановление. Действие вызывающей стороны библиотеки: зарегистрируйте отклонение как новую утверждённую запись EXC-NNN или исправьте рендерер, чтобы устранить отклонение.

Ввод HTML и CSS

HtmlParsingException

• Когда генерируется. Когда не удаётся разобрать HTML-ввод или построить DOM: недопустимые объявления кодировки, нарушения лимита размера ввода, чрезмерная глубина вложенности, переполнение количества элементов и ошибки структуры таблицы, такие как максимальное число строк. Исчерпание ресурсов, специфичное для CSS, сообщается вместо этого через CssParserLimitExceededException и CssResolutionBudgetExceededException.
• Контекст. getContext() возвращает html_snippet (короткий, усечённый фрагмент проблемного HTML), position (байтовое смещение или -1, если неизвестно) и rule (нарушенное ограничение парсера). Типизированные геттеры: getHtmlSnippet(), getPosition(), getRule().
• Восстановление. Действие разработчика: упростите HTML-ввод или скорректируйте лимиты парсера.

CssParserLimitExceededException

• Когда генерируется. Когда CSS-ввод превышает настроенный лимит безопасности парсера. Через именованные конструкторы охвачены две категории: forByteLimit() (таблица стилей слишком велика для безопасной обработки регулярными выражениями) и forNestingDepth() (слишком глубокая рекурсия вложенности CSS). Оба сообщения называют фактическое значение и лимит.
• Контекст. getContext() возвращает limit_type (byte или nesting_depth), actual и limit.
• Восстановление. Действие разработчика: разбейте таблицу стилей на меньшие листы или уменьшите глубину вложенности, или повысьте настроенный лимит.

CssResolutionBudgetExceededException

• Когда генерируется. Когда разрешение CSS :has() превышает свой бюджет обхода. Двухпроходный резолвер :has() обеспечивает строгий бюджет посещения узлов, чтобы предотвратить квадратичные обходы документа из-за патологических селекторов; как только общее число посещений превышает лимит, таблица стилей отклоняется как слишком сложная. Сообщение называет число посещений и бюджет.
• Контекст. getContext() возвращает visits и budget. Типизированные геттеры: getVisits(), getBudget().
• Восстановление. Действие разработчика: уменьшите сложность селекторов или повысьте настроенный бюджет.

Шрифты и изображения

FontNotFoundException

• Когда генерируется. Когда файл шрифта не удаётся найти или прочитать на уровне файловой системы: запрошенное семейство или путь не существует, не читается, или настроенный каталог шрифтов недоступен. Данные шрифта могут быть корректными — это сигнализирует лишь о том, что до них нельзя добраться. Сообщение перечисляет пути поиска.
• Контекст. getContext() возвращает font_name, search_paths (список) и fallback_attempted (булево значение). Типизированные геттеры: getFontName(), getSearchPaths(), wasFallbackAttempted().
• Восстановление. Действие разработчика: проверьте путь к шрифту. Действие инфраструктуры: исправьте права доступа к файлу или каталогу шрифта.

FontParsingException

• Когда генерируется. Когда файл шрифта найден, но его содержимое непригодно: он повреждён, в неподдерживаемом формате или в нём отсутствуют обязательные таблицы. Охватывает сбои структурной проверки при разборе TrueType, Type 1, CFF и OpenType — усечённые заголовки, недопустимые каталоги таблиц, отсутствующие обязательные таблицы (head, hhea, OS/2), ошибки распаковки и нарушения размера. Сообщение называет файл и ошибку разбора.
• Контекст. getContext() возвращает font_file и parse_error. Типизированные геттеры: getFontFile(), getParseError().
• Восстановление. Действие разработчика: замените файл шрифта корректным.

ImageProcessingException

• Когда генерируется. Когда изображение не удаётся декодировать, оно в неподдерживаемом формате или не проходит обработку GD/Imagick: нераспознаваемые магические байты, повреждённые данные JPEG, неподдерживаемые типы MIME, нарушения лимита размера файла и сбои выделения ресурсов GD. Изображение было доступно, но его пиксельные данные не удалось извлечь для встраивания.
• Контекст. getContext() возвращает image_path (пустой для встроенных данных), format (обнаруженный или ожидаемый, например jpeg, png, unknown) и operation (например decode, resize, embed). Типизированные геттеры: getImagePath(), getFormat(), getOperation().
• Восстановление. Действие разработчика: предоставьте корректный, поддерживаемый файл изображения.

Вывод, компоновка и сериализация

CompressionException

• Когда генерируется. Когда сжатие или распаковка FlateDecode (zlib) завершается сбоем — сбои gzcompress/gzuncompress для потоков содержимого, данных шрифтов, содержимого страниц, данных вложений и потоков перекрёстных ссылок. Обычно это повреждённый входной поток, недостаток памяти или отсутствующее расширение zlib.
• Контекст. getContext() возвращает algorithm (имя фильтра, например FlateDecode, LZWDecode) и stream_length (длина в байтах или -1, если неизвестна). Типизированные геттеры: getAlgorithm(), getStreamLength().
• Восстановление. Действие инфраструктуры: убедитесь, что ext-zlib загружено и памяти достаточно.

WriterException

• Когда генерируется. Когда сериализация PDF, линеаризация или вывод ввода-вывода завершается сбоем: ошибки записи потока PdfWriter, повреждение таблицы перекрёстных ссылок, сбои генерации заголовка/трейлера, сбои разрешения объектных ссылок, ошибки записи файла и переполнения буфера вывода. Корректный документ в памяти не удалось сериализовать в корректный поток байтов. Сообщение называет этап.
• Контекст. getContext() возвращает output_path (пустой для строкового вывода) и writer_state (этап, например header, body, xref, trailer). Типизированные геттеры: getOutputPath(), getWriterState().
• Восстановление. Действие инфраструктуры: проверьте место на диске, права доступа к файлу и поток вывода.

PageLayoutException

• Когда генерируется. Когда не удаётся удовлетворить ограничения компоновки страницы: нарушения колоночной компоновки (недостаточная ширина, недопустимое число колонок), переполнение содержимого за границы страницы и конфликты полей. Запрошенная компоновка геометрически невозможна для заданных размеров страницы и содержимого. Сообщение называет номер страницы, если он известен, и нарушенное ограничение.
• Контекст. getContext() возвращает page_number (отсчёт с единицы или 0, если неизвестен) и constraint. Типизированные геттеры: getPageNumber(), getConstraint().
• Восстановление. Действие разработчика: скорректируйте размер страницы, поля, настройки колонок или содержимое.

TemplateException

• Когда генерируется. Когда операция импорта или повторного использования PDF-шаблона завершается сбоем в TemplateManager: недопустимые переходы состояния шаблона (начало или завершение шаблонов вне последовательности), ссылка на несуществующий шаблон и сбои сжатия потока при сериализации шаблона. Сообщение называет операцию и идентификатор шаблона, если он назначен.
• Контекст. getContext() возвращает template_id (пустой, если ещё не назначен) и operation (например begin, end, use, serialize). Типизированные геттеры: getTemplateId(), getOperation().
• Восстановление. Действие разработчика: исправьте последовательность использования шаблона или исходный PDF.

Инварианты потока содержимого

ContentStreamBalanceException

• Когда генерируется. Когда ContentStreamBuilder обнаруживает несбалансированную пару операторов при закрытии потока (или в середине потока, когда инварианты проверяются немедленно). Он фиксирует счётчики глубины, которые не прошли проверку баланса, чтобы по журналу можно было определить, какой источник пропустил q, BT или BMC без соответствующего Q, ET или EMC. Согласно ISO 32000-2:2020 §8.4.2 (стек графического состояния), §9.4.1 (текстовые объекты) и §14.6 (маркированное содержимое).
• Контекст. getContext() возвращает graphics_depth, text_block_depth, marked_content_depth и offending_operator. Типизированные геттеры: getGraphicsDepth(), getTextBlockDepth(), getMarkedContentDepth(), getOffendingOperator().
• Восстановление. Действие разработчика: найдите источник, который открыл конструкцию, не закрыв её.

GraphicsStateBalanceException

• Когда генерируется. Когда поток содержимого PDF закрывается с несбалансированными операторами q/Q. ISO 32000-2:2020 §8.4.2 требует, чтобы каждое сохранение графического состояния (q) было сопоставлено ровно с одним восстановлением (Q) до конца потока; дисбаланс пропускает преобразование, путь отсечения, цвета и намерение рендеринга в последующие страницы или Form XObject. Генерируется только при включённой строгой проверке графического состояния (NEXTPDF_GFXSTATE_STRICT=1); в нестрогом режиме вместо этого выдаётся предупреждение через trigger_error().
• Контекст. getContext() возвращает save_depth (положительное при слишком большом числе сохранений, отрицательное при слишком большом числе восстановлений). Типизированный геттер: getSaveDepth().
• Восстановление. Действие разработчика: найдите несопоставленную пару save()/restore().

MissingShadingResourceException

• Когда генерируется. Когда ConicGradientRenderer::render() вызывается без контекста реестра ресурсов Shading. Критическое изменение версии v10.0.0 удалило прежний неявный суррогатный путь карты маркеров: вызывающие стороны должны конструировать рендерер с ShadingResourceRegistryInterface, чтобы косвенный объект /ShadingType 4 был зарегистрирован в подсловаре ресурсов Shading страницы (ISO 32000-2 §8.7.4.2 / §8.7.4.3). Сообщение называет контекст вызывающей стороны и указывает на примечание о миграции v9.x→v10.0.
• Контекст. getContext() возвращает context (короткая метка контекста вызывающей стороны, например ConicGradientRenderer::render).
• Восстановление. Действие вызывающей стороны библиотеки: подключите экземпляр реестра ресурсов Shading в конструктор рендерера перед вызовом render().

Линеаризация (Fast Web View)

LinearizationInvariantException

• Когда генерируется. Когда трёхпроходный Linearizer версии v2 обнаруживает, что его утверждения MEASURE → PLACE → FILL были нарушены: число байтов в Pass 3, не совпадающее с длиной файла, предсказанной в Pass 1 (смещение дрейфа), заполнитель словаря линеаризации слишком мал для сериализованной ширины или смещение /H [offset length] потока подсказок, не совпадающее с финальным выводом. Выявление этого вместо выпуска повреждённого PDF — заявленная гарантия безопасности.
• Контекст. getContext() возвращает invariant (имя нарушенного инварианта), expected, actual и delta (знаковая разность). Типизированные геттеры: getInvariant(), getExpectedValue(), getActualValue().
• Восстановление. Действие сопровождающего: подайте отчёт об ошибке — эти инварианты должны выполняться для всех корректно сформированных входных данных. Зафиксируйте связанное предыдущее исключение.

LinearizationUnimplementedException

• Когда генерируется. Когда флаг возможности линеаризатора задан для бэкенда, намеренно отключённого. В настоящее время генерируется только для linearizerVersion === 'v1-noop', настройки экстренного понижения, которая отклоняет все попытки линеаризации во время выполнения без изменения кода или повторного развёртывания — полезно для аварийного отключения Fast Web View в продакшене.
• Контекст. getContext() возвращает reason (краткое читаемое человеком объяснение). Типизированный геттер: getReason().
• Восстановление. Действие оператора / инженера релиза: скорректируйте конфигурацию или обновитесь до исправленной версии бэкенда.

Инварианты соответствия и профиля

ConformanceViolationException

• Когда генерируется. Когда запрошенную возможность нельзя вывести без нарушения объявленного контракта соответствия ISO документа, и движок завершается отказом, а не записывает несоответствующий объект. Канонический триггер — мультимедийная аннотация Screen или действие Rendition (ISO 32000-2:2020 §12.5.6.18 / §13.2) под архивным профилем PDF/A, который запрещён каждой частью PDF/A (серия ISO 19005) — файл не прошёл бы проверку veraPDF, поэтому движок отказывает заранее.
• Контекст. getContext() возвращает conformance_mode (объявленный режим, например pdfa4) и feature (отклонённая возможность, например Screen annotation). Оба являются публичными свойствами readonly. Причина указана в сообщении исключения.
• Восстановление. Действие разработчика: уберите мультимедийный вызов для архивного вывода или нацельтесь на неархивный профиль соответствия (по умолчанию ConformanceMode::Plain).

PdfRViolationException

• Когда генерируется. Когда нарушается инвариант соответствия PDF/R-1 (ISO 23504-1:2020), либо при конструировании объекта-значения (профили PdfRStrip, PdfRPage, PdfRDocument), либо во время работы валидатора (PdfRValidator). Он фиксирует нарушенный нормативный пункт и однострочное описание нарушения, чтобы потребители аудита могли направить находки в правильный подпункт §6 без разбора свободного текста.
• Контекст. getContext() возвращает standard (всегда ISO 23504-1:2020), clause (путь к пункту, например 6.6.1) и violation. Типизированные геттеры: getClause(), getViolation().
• Восстановление. Действие разработчика: исправьте отклонённый ввод или пересоберите документ так, чтобы он соответствовал указанному пункту.

Генерация штрихкодов

BarcodeException

• Когда генерируется. Когда генерация штрихкода завершается сбоем из-за недопустимых данных или ошибок кодирования во всех поддерживаемых символиках (Code 39/128, UPC-A/E, EAN-8/13, Interleaved/Standard 2-of-5, POSTNET, PLANET, MSI, ISBN, ISSN, QR Code, PDF417, DataMatrix, JabCode), а также из-за сбоев рендеринга GD при создании изображения. Значение штрихкода ограничивается выдержкой в 128 байт в сообщении и контексте — слишком длинные или двоичные полезные нагрузки хранятся усечёнными с маркером ... (<N> bytes, truncated), чтобы их нельзя было целиком скопировать в журнал.
• Контекст. getContext() возвращает barcode_type (символика, например QRCODE, EAN13, CODE128) и value (усечённое значение). Типизированные геттеры: getBarcodeType(), getValue().
• Восстановление. Действие разработчика: исправьте данные штрихкода или выбор символики.

BarcodeEncoderNotFoundException

• Когда генерируется. Из BarcodeEncoderRegistry, когда запрошенный тип кодировщика неизвестен или его гейт возможности закрыт. Он также реализует PSR-11 Psr\Container\NotFoundExceptionInterface, поэтому реестр является контейнером, соответствующим стандарту. Сообщение называет символику и причину.
• Контекст. Не переопределяет getContext(), поэтому возвращает пустой массив. Значения type и reason доступны через геттеры getType() и getReason() и в сообщении.
• Восстановление. Действие разработчика: зарегистрируйте кодировщик или установите пакет, который его предоставляет (например, nextpdf/pro для Micro QR / DotCode / HanXin / JabCode).

Криптография, шифрование и подписи

EncryptionException

• Когда генерируется. Когда шифрование или расшифровка PDF завершается сбоем: сбои шифрования/расшифровки AES-256-CBC, ошибки OpenSSL, недопустимые размеры IV, сбои вычисления хеша и ошибки вычисления значений UE/OE. Обычно это отсутствующее или неправильно настроенное расширение OpenSSL, недопустимый ключевой материал или повреждённые зашифрованные данные. Сообщение называет операцию и алгоритм.
• Контекст. getContext() возвращает algorithm (например AES-256-CBC) и operation (например encrypt, decrypt, key_derivation). Типизированные геттеры: getAlgorithm(), getOperation().
• Восстановление. Действие инфраструктуры: убедитесь, что OpenSSL доступен и правильно настроен. См. Шифрование и разрешения.

UnsupportedAlgorithmException

• Когда генерируется. Когда криптографический алгоритм нельзя выполнить в текущей среде выполнения: недоступно требуемое PHP-расширение, в базовой библиотеке отсутствует примитив, встроенное расширение hash не может синтезировать вариант SHAKE/XOF или алгоритм не зарегистрирован в SignatureAlgorithmRegistry. Движок не должен молча деградировать до более слабого примитива, поэтому он вместо этого выявляет это. Статическая фабрика nonFipsHostUnderFipsProfile() генерирует его (с идентификатором алгоритма regulatory-profile:fips), когда выбран RegulatoryProfile::FIPS, но не удаётся подтвердить FIPS-валидированный провайдер OpenSSL (и FIPS_ABSENT, и INDETERMINATE завершаются отказом).
• Контекст. getContext() возвращает algorithm (имя или OID, например shake256, Ed25519, AES-256-GCM) и reason (действенный для оператора). Типизированные геттеры: getAlgorithm(), getReason().
• Восстановление. Действие оператора: установите отсутствующее расширение или обновите среду выполнения; для гейта FIPS установите FIPS-валидированную сборку OpenSSL или задайте NEXTPDF_FIPS_MODE явно. Действие разработчика: зарегистрируйте пользовательский дескриптор алгоритма через SignatureAlgorithmRegistry::register().

SignatureException

• Когда генерируется. Когда операция цифровой подписи завершается сбоем: работа с сертификатами и закрытыми ключами (разбор PKCS#12, декодирование PEM/DER, проверка X.509), построение PKCS#7/CMS, формат подписи ECDSA, нарушения размера контейнера, кодирование DER и оркестрация PAdES. Ошибки, специфичные для TSA, сообщаются вместо этого более специфичным TsaException. Предпочитайте типизированные именованные фабрики позиционному конструктору; каждая привязывает первопричину к концу сообщения. Примеры: ltvCapabilityMissing() (B-LT/B-LTA требует nextpdf/enterprise), tsaRequired() / tsaUrlEmpty() / tsaEmptyToken(), httpClientMissing(), hsmSignerMissing() / hsmSignatureEmpty(), signatureContentsNotFound() / signatureContentsPaddingCorrupt(), unexpectedKeyType(), pemDecodingFailed(), семейство Ed25519 (ed25519SignatureMalformed(), ed25519RoundTripVerifyFailed(), ed25519KeyParseFailed(), ed25519SeedInvalid(), ed25519SecretKeyMalformed(), ed25519PublicKeyInvalid()), documentTimestampNotEmitted(), algorithmPolicyRejected(), digestOnlyAlgorithmRefused(), encryptedLtvUnsupported(), incrementalUpdateWriterMissing(), а также пара статусов OCSP nonSuccessfulOcspResponseStatus() / reservedOcspResponseStatus() (RFC 6960 §4.2.1). Эти фабрики завершаются отказом, а не выдают молча пониженную подпись.
• Контекст. getContext() возвращает cert_info (DN субъекта или отпечаток, либо пустое), signature_level (попытанный уровень PAdES, например B-B, B-T, B-LT, B-LTA) и detail (действенная диагностика, пустая для устаревшего позиционного конструктора). Типизированные геттеры: getCertInfo(), getSignatureLevel(), getDetail().
• Восстановление. Действие разработчика: исправьте конфигурацию сертификата/ключа. Для фабрик с отсутствующей возможностью установите названный пакет. См. Сбои подписи и метки времени для записей «симптом и решение» по каждой фабрике.

BlackPointCompensationUnsupportedException

• Когда генерируется. Из NullBlackPointCompensationTransform::transform(), когда вызывающая сторона просит нулевой адаптер применить преобразование компенсации чёрной точки ISO 18619, отличное от Default. Нулевой адаптер — это безопасный запасной вариант для сред без бэкенда управления цветом; выдача преобразованного образца без реального модуля управления цветом молча исказила бы отчёт о преобразовании. В отличие от большинства записей здесь, он наследуется напрямую от \RuntimeException, а не от NextPdfException, поэтому существующие пути catch (\RuntimeException) продолжают работать.
• Контекст. Нет getContext(); это простое \RuntimeException. Детали находятся в сообщении.
• Восстановление. Действие разработчика: зарегистрируйте реальное BlackPointCompensationTransform (LittleCMS, Argyll, чистый PHP) или ограничьте /UseBlackPtComp значением BlackPointCompensation::Default.

Сборка документа и доступность

UnsupportedSourceDocumentException

• Когда генерируется. Когда исходный документ нельзя безопасно скопировать в вывод слияния/разбиения, и операция завершается отказом, а не выдаёт повреждённый или скомпрометированный по безопасности результат. Используйте именованные фабрики: encrypted() (ISO 32000-2 §7.6 — содержимое нельзя скопировать без ключа), signed() (§12.8 — копирование страниц сделало бы недействительным байтовый диапазон подписи), unsupportedStreamFilter() (фильтр, который читатель графа объектов не может обработать без потерь), multipleInteractiveForms() (задокументированное ограничение: более одного источника несёт непустой /AcroForm, §12.7) и splitWithInteractiveForm() (задокументированное ограничение: разбиение страниц источника с формой осиротило бы виджеты). Наследуется напрямую от \RuntimeException, а не от NextPdfException.
• Контекст. Нет getContext(); это простое \RuntimeException. Причина и номер затронутого объекта названы в сообщении.
• Восстановление. Действие разработчика: сначала расшифруйте источник или предоставьте ключ; для подписанных источников подписывайте после слияния; для слияний с несколькими формами уплощите или удалите поля формы у всех источников, кроме одного; для разбиений источников с формой уплощите форму перед разбиением.

InvalidBcp47TagException

• Когда генерируется. Из Bcp47Validator::validate(), когда кандидатный языковой тег некорректен по ABNF RFC 5646 §2.1 или не проходит поиск в курируемом реестре. Специфичен для домена BCP-47 / ISO 14289-2:2024 §8.4.4, отличается от InvalidConfigException, чтобы вызывающие стороны ниже по потоку от шва доступности могли перехватить узкий тип. Пара предикатов Bcp47Validator::isWellFormed() / isValid() остаётся обратно совместимой поверхностью с возвращаемым значением для вызывающих сторон, предпочитающих ветвление исключениям.
• Контекст. getContext() возвращает tag (кандидат ровно в том виде, в каком передан) и reason (стабильный машиночитаемый код отклонения, например empty-string, well-formed-shape, unregistered-primary, duplicate-variant). Типизированные геттеры: getTag(), getReason().
• Восстановление. Действие разработчика: исправьте языковой тег на корректно сформированный, зарегистрированный тег BCP-47. См. Шрифты и тегирование.

FormFieldAccessibilityException

• Когда генерируется. Когда интерактивное поле формы опиралось бы на синтетическое (не предоставленное автором) доступное имя при создании документа PDF/UA со включённым строгим контролем доступных имён полей. Вывод PDF/UA по умолчанию выдаёт синтетическое запасное имя в /Contents виджета, чтобы поле никогда не оставалось безымянным; строгий режим вместо этого требует, чтобы автор предоставил осмысленное имя (всплывающую подсказку или подпись для кнопки без действия), чтобы пользователи программ чтения с экрана получали реальное описание (ISO 14289-2:2024 §8.10.2).
• Контекст. Не переопределяет getContext(), поэтому возвращает пустой массив. $fieldId — это публичное свойство readonly; причина находится в сообщении.
• Восстановление. Действие разработчика: предоставьте всплывающую подсказку / доступное имя для названного поля перед созданием строгого документа PDF/UA или отключите строгий режим. См. Проверка PDF/A и PDF/UA.

VendorExtensionRegistryConflictException

• Когда генерируется. Из VendorExtensionRegistry::register(), когда вызывающая сторона повторно регистрирует известный префикс вендора расширения разработчика PDF (ISO 32000-2:2020 §7.12.1) с описанием, не согласующимся с уже зарегистрированными метаданными. Дескрипторы доступны только для добавления и проверяются на конфликты; типизированное исключение заменило обобщённое \RuntimeException, чтобы вызывающие стороны могли перехватить этот конкретный класс.
• Контекст. getContext() возвращает prefix, existing_description и attempted_description. Типизированные геттеры: getPrefix(), getExistingDescription(), getAttemptedDescription().
• Восстановление. Действие разработчика: зарегистрируйте префикс с существующим описанием или используйте отдельный префикс; не перезаписывайте зарегистрированные метаданные.

Экспорт аудита

AuditExportException

• Когда генерируется. Когда сборка пакета экспорта аудита, генерация матрицы прослеживаемости или проекция схемы завершается сбоем во время выполнения. Охватывает ввод-вывод по claims.json / manifest.json, JSON-кодирование/декодирование канонического пакета, а также несоответствие версии схемы на пути обратной совместимости AuditExporter::projectToV1(). Сообщение называет этап, артефакт, если он известен, и детали.
• Контекст. getContext() возвращает stage (например read_claims, encode_bundle, project_v1), detail и artefact (путь или schema_version, который вызвал сбой). Типизированные геттеры: getStage(), getDetail(), getArtefact().
• Восстановление. Действие специалиста по соответствию / DevOps: проверьте пути входных артефактов, перегенерируйте claims.json из чистого запуска или пересоберите манифест перед повторной попыткой экспорта.

Объекты-значения нарушений

Это не исключения. Это неизменяемые объекты-значения, которые движок возвращает, чтобы описать отдельное нарушение; они не несут getContext().

ComplianceViolation

• Что это. Объект-значение final readonly, представляющий одно нарушение правила, о котором сообщил внешний валидатор (veraPDF или эквивалент), включая ссылку на пункт ISO и местоположение в структуре PDF.
• Поля. Публичные свойства readonly: ruleId (идентификатор правила валидатора, например 6.1.2-1), clause (ссылка на пункт ISO, например ISO 19005-1:2005, 6.1.2), severity (например error, warning), location (путь объекта в структуре PDF) и message (читаемое человеком описание).
• Использование. Изучите коллекцию, возвращённую валидатором соответствия; направляйте или отображайте каждую запись по severity и clause. См. Проверка PDF/A и PDF/UA.

RuleViolation

• Что это. Объект-значение final readonly, представляющий одно нарушение бизнес-правила Schematron / EN 16931, возвращённое SchematronRunnerInterface::runRules() и агрегированное внутри ValidationResult::$ruleViolations. Стабильность экспериментальная.
• Поля. Публичные свойства readonly: ruleId (идентификатор EN 16931, такой как BR-{n}, BR-CO-{n}, BR-CL-{n}, BR-DEC-{n} или специфичный для уровня пакет), severity (перечисление RuleSeverity), message (текст правила, en-GB), xpath (XPath во встроенном XML, null для правил уровня документа) и semanticPath (путь BG/BT в точечной нотации, такой как BG-22.BT-106, null для структурных нарушений).
• Использование. Изучите коллекцию в результате проверки; направляйте или отображайте каждую запись по severity, ruleId и локатору.

См. также

• Указатель справочника по ошибкам
• Указатель базы знаний
• Сбои подписи и метки времени
• Шифрование и разрешения
• Шрифты и тегирование
• Проверка PDF/A и PDF/UA