Ошибки соответствия

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

Эти записи охватывают два исключения в пространстве имён NextPDF\Compliance\Exception. Оба генерируются подсистемой соответствия: каноническим конвейером хеша пункта и жизненным циклом соответствия (кеш Document Compliance Evidence, промоутер из проверенного в терминальное состояние и наблюдатель остывания).

Оба класса являются final и наследуются от NextPdfException, который сам наследуется от \RuntimeException и реализует ContextAwareExceptionInterface. Ни один из подклассов не переопределяет getContext(), поэтому оба наследуют базовую реализацию, которая возвращает пустой массив. Диагностические детали несутся в сообщении исключения, а не в getContext(). Перехватывайте любой из типов как NextPdfException или как \RuntimeException, если у вас есть существующие обработчики.

Требования к хешу пункта во время выполнения

ClauseHashRequirementException

• Когда генерируется. Из ClauseHash::compute(), когда хост-среда выполнения PHP не имеет жёсткого требования канонического конвейера хеша пункта. В настоящее время единственное такое требование — ext-intl, используемое для нормализации Unicode Normalization Form KC (NFKC). Единственная точка генерации выдаёт сообщение ClauseHash requires ext-intl for NFKC normalisation.
• Почему завершается при отказе. composer.json предписывает ext-intl, поэтому это срабатывает только в неправильно настроенной нижестоящей среде, которая упаковывает NextPDF без intl. Конвейер отказывается вычислять не-NFKC-нормализованный дайджест, а не молча выдаёт хеш, несовместимый с любым другим потребителем хеша пункта.
• Контекст. getContext() возвращает пустой массив. Причина указана в сообщении.
• Восстановление. Действие оператора: установите и включите PHP-расширение intl на хосте, затем повторите. Обходного пути в коде нет; нормализованный дайджест нельзя получить без него.

Сбои жизненного цикла соответствия

ComplianceLifecycleException

• Когда генерируется. Из подсистемы жизненного цикла соответствия, когда структурный инвариант claims.json или его конвейера сохранения нарушается во время выполнения. Точки генерации охватывают промоутер из проверенного в терминальное состояние, наблюдатель остывания и инкрементный кеш Document Compliance Evidence. Конкретные триггеры таковы:
  • Некорректный корневой документ — claims.json не декодируется в объект или claims.standards не является JSON-объектом (например, claims.json must decode to an object, claims.standards must be a JSON object, claims.json invalid JSON: <detail>).
  • Сбои чтения — claims.json отсутствует или нечитаем (например, claims.json not found at: <path>, claims.json unreadable at <path>).
  • Сбои ввода-вывода атомарной записи в конвейере сохранения — открытие temp, flock, короткая запись, fflush, атомарное rename и запись sidecar (например, tmp open failed at <path>, tmp flock failed at <path>, tmp write short for <path>, tmp fflush failed at <path>, atomic rename failed for <path>, sha256 sidecar write failed at <path>).
  • Сбои на стороне кодировщика — json_encode() отклоняет исходящую полезную нагрузку (например, claims.json encode failed: <detail>).
  • Сбои начальной загрузки кеша свидетельств — инкрементный кеш не может создать или записать свой корневой каталог (например, IncrementalEvidenceCache: cannot create rootDir <path>, IncrementalEvidenceCache: write failed for <path>, IncrementalEvidenceCache: rename failed for <path>).
  • Нарушения внутренних инвариантов — например, gmdate produced empty timestamp или fqClauseId: empty clauseKey.
• Почему он существует. Это типизированная по домену замена прежнего использования \RuntimeException в коде жизненного цикла и кеша. Он не меняет контракт времени выполнения, потому что NextPdfException уже наследуется от \RuntimeException; существующие предложения catch (\RuntimeException $e) продолжают работать.
• Контекст. getContext() возвращает пустой массив. Проблемный путь и конкретный сбой названы в сообщении; сбои JSON-декодирования и кодирования также связывают базовое \JsonException как предыдущее исключение, поэтому читайте getPrevious() для них.
• Восстановление.
  • Для ошибок формы и чтения это действие оператора: изучите claims.json по пути, названному в сообщении, подтвердите, что это корректно сформированный JSON, чей корень и член standards являются объектами, и подтвердите, что он присутствует и читаем.
  • Для ошибок атомарной записи и начальной загрузки кеша проверьте существование целевого каталога, права доступа и свободное место, затем повторите.
  • Для сбоев на стороне кодировщика это действие разработчика: полезная нагрузка, переданная json_encode(), не кодируется. Зафиксируйте связанное предыдущее исключение и сообщение для отчёта о дефекте.

См. также

• Указатель справочника по ошибкам
• Проверка PDF/A и PDF/UA