Base de conhecimento para solução de problemas

O que esta base de conhecimento cobre

Use esta base de conhecimento para relacionar uma falha que você observa à causa e à resolução. Cada entrada se baseia nas próprias classes de exceção do motor, nos testes de caminho de falha e nas proteções no código-fonte, não em especulação. Se o motor não tiver um caminho de código para determinada falha, esta base de conhecimento não inventa um.

A base de conhecimento inclui quatro páginas temáticas:

• Validação de assinatura — assinaturas inválidas, cadeias incompletas, revogação desconhecida e falhas de carimbo de tempo.
• Validação de PDF/A e PDF/UA — problemas de Portable Document Format/Archive (PDF/A) e Portable Document Format/Universal Accessibility (PDF/UA), incluindo intenção de saída ausente, conteúdo sem marcação, idioma ausente e falhas de fonte incorporada.
• Fontes e marcação — fonte não encontrada, subconjunto, cobertura CJK e problemas de árvore de estrutura.
• Criptografia e permissões — falhas de descriptografia e o limite das flags de permissão.

Como ler uma entrada

Cada entrada é composta por cinco partes:

1. Sintoma — o que você observa: uma classe de exceção, um fragmento de mensagem ou um veredito de validador subsequente.
2. Causa provável — a condição de entrada ou configuração que o motor relata.
3. Evidência / diagnóstico — como confirmar a causa. Esta parte identifica a classe de exceção exata, o campo getContext() ou o teste que demonstra o comportamento, para que você possa verificar em vez de adivinhar.
4. Resolução — as etapas, em ordem, para eliminar a causa.
5. Relacionado — a página de referência do módulo ou a entrada relacionada para ler em seguida.

Identifique uma falha pelo tipo de exceção

O NextPDF identifica um erro pela classe PHP, não por um código de erro como string. Não existe nenhuma constante NPDF-#### nas classes de exceção. Capture a exceção folha quando precisar de uma resposta direcionada e leia ContextAwareExceptionInterface::getContext() para obter campos de diagnóstico estruturados. Use NextPDF\Exception\NextPdfException como o tipo base; falhas de segurança também usam NextPDF\Security\Exception\SecurityException.

Para a hierarquia completa e as regras de ordem para captura, leia a referência de exceções.

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

Escopo e limites

Esta base de conhecimento cobre como o motor detecta e relata falhas. Ela não cobre vereditos de conformidade de validadores externos, como veraPDF ou callas; essas ferramentas aplicam seus próprios conjuntos de regras. Quando o motor recusa uma operação para manter um documento dentro de um perfil, como recusar criptografia sob PDF/A, a entrada correspondente cita a cláusula que rege e a exceção que a aplica.

Veja também

• Referência de exceções — hierarquia completa, ordem de captura e o contrato getContext() correspondente
• Referência de conformidade — verificadores de perfil PDF/A, PDF/UA e PDF/X

Glossário: exceção ciente de contexto