Referência de erros

Esta é a lista de referência das exceções que o NextPDF Core gera, organizada por área. Cada página de categoria documenta, por classe, quando ela é gerada, os dados estruturados que carrega e como se recuperar. Se você está diagnosticando um sintoma em vez de capturar uma classe específica, comece pelos guias de solução de problemas — eles são organizados pelo que você observa.

Visão geral

• A maioria das exceções estende uma única base, NextPdfException, então você pode capturar toda a família com um único bloco catch.
• NextPdfException é sensível ao contexto: ela implementa ContextAwareExceptionInterface, que declara getContext(): array. Muitas subclasses sobrescrevem getContext() para retornar chaves de diagnóstico estruturadas; outras herdam o padrão vazio e expõem seus detalhes por meio da mensagem e de getters tipados.
• Um pequeno número de exceções de baixo nível estende a \RuntimeException do PHP diretamente, em vez de NextPdfException. Essas não são sensíveis ao contexto e carregam seus detalhes em propriedades públicas readonly. Cada página de categoria as sinaliza explicitamente.
• Dois tipos de conformidade nomeados …Violation (ComplianceViolation, RuleViolation) são objetos de valor, não exceções — eles descrevem uma constatação sem serem gerados.

O tipo base e o contrato de contexto

NextPdfException é uma classe abstrata que estende \RuntimeException e implementa ContextAwareExceptionInterface. O contrato é pequeno:

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

Um handler defensivo, portanto, fica assim:

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

Como algumas falhas surgem como uma \RuntimeException simples (consulte as notas de cada categoria), um limite com cinto e suspensórios também pode capturar \RuntimeException e inspecionar o tipo concreto.

Categorias

• Erros do core e gerais — falhas de documento, mesclagem, acessibilidade, fatura eletrônica, espaço de cores, objeto de valor e modo estrito, além dos tipos base compartilhados.
• Erros de segurança, assinatura e PKI — criação e verificação de assinaturas, carimbos de tempo, validação de caminho PKI e de restrições de nome, hashing, integridade e PKCS#11.
• Erros de renderização e I/O — layout de HTML e mídia paginada, fontes e text shaping, o writer e o reader, e os metadados XMP.
• Erros de runtime e suporte — transporte HTTP, resiliência (circuit breaker, modo degradado), observabilidade e tratamento de manifestos.
• Erros do Accelerator — o transporte do sidecar de aceleração opcional.
• Erros de conformidade — requisitos de clause-hash e o ciclo de vida de conformidade.

Veja também

• Solução de problemas — guias organizados por sintoma para validação de assinatura, criptografia e permissões, fontes e tagueamento e validação de PDF/A e PDF/UA.