Erros de conformidade

Escopo

Estas entradas cobrem as duas exceções no namespace NextPDF\Compliance\Exception. Ambas são geradas pelo subsistema de conformidade: o pipeline canônico de clause-hash e o ciclo de vida de conformidade (o cache de Document Compliance Evidence, o promoter de audited-to-terminal e o observer de cooldown).

Ambas as classes são final e estendem NextPdfException, que por sua vez estende \RuntimeException e implementa ContextAwareExceptionInterface. Nenhuma das subclasses sobrescreve getContext(), então ambas herdam a implementação base, que retorna um array vazio. O detalhe de diagnóstico é carregado na mensagem da exceção, não em getContext(). Capture qualquer um dos tipos como NextPdfException, ou como \RuntimeException se você tiver handlers existentes.

Requisitos de runtime de clause-hash

ClauseHashRequirementException

• Quando é gerada. A partir de ClauseHash::compute() quando o runtime PHP do host não tem um requisito rígido do pipeline canônico de clause-hash. Atualmente o único requisito desse tipo é ext-intl, usado para Unicode Normalization Form KC (NFKC). O único site de throw gera a mensagem ClauseHash requires ext-intl for NFKC normalisation.
• Por que falha de forma fechada. O composer.json exige ext-intl, então isto dispara apenas em um downstream mal configurado que empacota o NextPDF sem intl. O pipeline se recusa a calcular um digest não normalizado por NFKC em vez de emitir silenciosamente um hash incompatível com todos os outros consumidores de clause-hash.
• Contexto. getContext() retorna um array vazio. A causa é informada na mensagem.
• Recuperação. Ação do operador: instale e ative a extensão PHP intl no host, então tente novamente. Não há solução alternativa em código; o digest normalizado não pode ser produzido sem ela.

Falhas de ciclo de vida de conformidade

ComplianceLifecycleException

• Quando é gerada. A partir do subsistema de ciclo de vida de conformidade quando um invariante estrutural em claims.json ou em seu pipeline de persistência é violado em tempo de execução. Os sites de throw abrangem o promoter de audited-to-terminal, o observer de cooldown e o cache incremental de Document Compliance Evidence. Os gatilhos concretos são:
  • Documento raiz malformado — claims.json não decodifica para um objeto, ou claims.standards não é um objeto JSON (por exemplo, claims.json must decode to an object, claims.standards must be a JSON object, claims.json invalid JSON: <detail>).
  • Falhas de leitura — claims.json está ausente ou ilegível (por exemplo, claims.json not found at: <path>, claims.json unreadable at <path>).
  • Falhas de I/O de gravação atômica no pipeline de persistência — abertura de temp, flock, gravação curta, fflush, rename atômico e gravação de sidecar (por exemplo, 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>).
  • Falhas do lado do encoder — json_encode() rejeita o payload de saída (por exemplo, claims.json encode failed: <detail>).
  • Falhas de bootstrap do cache de evidências — o cache incremental não consegue criar ou gravar seu diretório raiz (por exemplo, IncrementalEvidenceCache: cannot create rootDir <path>, IncrementalEvidenceCache: write failed for <path>, IncrementalEvidenceCache: rename failed for <path>).
  • Violações de invariante interno — por exemplo um gmdate produced empty timestamp ou fqClauseId: empty clauseKey.
• Por que existe. Esta é uma substituição tipada de domínio para o uso anterior de \RuntimeException no código de ciclo de vida e de cache. Ela não muda o contrato de runtime, porque NextPdfException já estende \RuntimeException; cláusulas catch (\RuntimeException $e) existentes continuam funcionando.
• Contexto. getContext() retorna um array vazio. O caminho problemático e a falha específica são informados na mensagem; falhas de decode e encode JSON também encadeiam a \JsonException subjacente como a exceção anterior, então leia getPrevious() para essas.
• Recuperação.
  • Para erros de formato e de leitura, esta é uma ação do operador: inspecione claims.json no caminho informado na mensagem, confirme que é JSON bem formado cuja raiz e cujo membro standards são objetos, e confirme que está presente e legível.
  • Para erros de gravação atômica e de bootstrap de cache, verifique a existência, as permissões e o espaço livre do diretório de destino, então tente novamente.
  • Para falhas do lado do encoder, esta é uma ação do desenvolvedor: o payload entregue a json_encode() não é codificável. Capture a exceção anterior encadeada e a mensagem para um relatório de defeito.

Veja também

• Índice de referência de erros
• Validação de PDF/A e PDF/UA