Exception: hierarquia de exceções tipadas

Visão geral

Toda exceção lançada pelo NextPDF estende uma única base abstrata, NextPdfException, permitindo que você trate qualquer erro do mecanismo com um único catch. Cada exceção de domínio implementa ContextAwareExceptionInterface e expõe campos de diagnóstico estruturados para logging e monitoramento de desempenho de aplicações (APM), sem precisar analisar a string da mensagem.

Instalação

composer require nextpdf/core:^3

Visão conceitual

A hierarquia tem três camadas:

RuntimeException (PHP SPL)
  └── NextPdfException (abstract; implements ContextAwareExceptionInterface)
        ├── InvalidConfigException
        ├── FontNotFoundException
        ├── FontParsingException
        ├── ImageProcessingException
        ├── SignatureException
        ├── EncryptionException
        ├── WriterException
        ├── PageLayoutException
        ├── HtmlParsingException
        ├── CompressionException
        ├── NotImplementedException
        ├── … (23 domain exceptions total)
        └── Strict\StrictModeViolation (abstract)
              ├── Strict\IncompatibleRenderingModeException
              ├── Strict\OracleConformanceFailure
              └── Strict\UnregisteredCssDeviation

NextPdfException estende RuntimeException da Standard PHP Library (SPL). Capturar RuntimeException também captura os erros do NextPDF. Capturar NextPdfException limita o handler aos erros do mecanismo. Capture uma classe folha para uma recuperação direcionada. A subárvore Strict\ agrupa as violações do modo de conformidade sob a classe abstrata StrictModeViolation, que por sua vez estende NextPdfException.

Contexto, não códigos em string. O NextPDF identifica um erro pelo tipo PHP, não por um código de erro em string. As classes de exceção não definem nenhuma constante de código NPDF-####. Em vez disso, ContextAwareExceptionInterface::getContext() retorna um array<string, mixed> de campos primitivos em snake_case, seguros para serialização em um payload de log ou APM. NextPdfException::getContext() retorna [] por padrão. Cada exceção de domínio sobrescreve esse método com campos específicos daquela falha. Por exemplo, FontNotFoundException::getContext() retorna font_name, search_paths e fallback_attempted. WriterException retorna output_path e writer_state. InvalidConfigException retorna config_key, given_value e expected_type. Os identificadores em string estáveis NEXTPDF_W_* pertencem ao enum não fatal WarningCode no módulo Support, não às exceções.

Acionabilidade. O docblock da classe de cada exceção de domínio declara quem pode agir sobre ela: o desenvolvedor, a infraestrutura ou quem chama a biblioteca. InvalidConfigException é um erro do desenvolvedor; corrija a configuração. FontNotFoundException é um erro do desenvolvedor ou da infraestrutura; verifique o caminho ou as permissões do arquivo. WriterException é um erro de infraestrutura; verifique o disco, as permissões ou o stream de saída. NotImplementedException é um erro de quem chama; remova a chamada ou fixe uma versão que entregue o follow-up indicado. Várias exceções oferecem construtores nomeados para causas-raiz precisas: SignatureException::ltvCapabilityMissing(), ::tsaRequired() e similares. Os operadores veem a causa real em vez de uma mensagem genérica.

Superfície da API

Símbolo	Tipo	Membros principais
NextPDF\Contracts\ContextAwareExceptionInterface	interface	getContext(): array<string, mixed>
NextPDF\Exception\NextPdfException	classe abstrata	estende RuntimeException; getContext() (padrão [])
NextPDF\Exception\InvalidConfigException	final	getConfigKey(), getGivenValue(), getExpectedType(), getContext()
NextPDF\Exception\FontNotFoundException	final	getFontName(), getSearchPaths(), wasFallbackAttempted(), getContext()
NextPDF\Exception\SignatureException	final	getCertInfo(), getSignatureLevel(), getDetail(), getContext(); construtores nomeados ltvCapabilityMissing(), tsaRequired(), httpClientMissing(), …
NextPDF\Exception\WriterException	final	getOutputPath(), getWriterState(), getContext()
NextPDF\Exception\PageLayoutException	final	getPageNumber(), getContext()
NextPDF\Exception\NotImplementedException	final	$feature, $followUp
NextPDF\Exception\Strict\StrictModeViolation	abstract	estende NextPdfException
NextPDF\Exception\Strict\IncompatibleRenderingModeException	final	estende StrictModeViolation

Conjunto completo de classes folha (23): BarcodeEncoderNotFoundException, BarcodeException, CompressionException, ContentStreamBalanceException, CssParserLimitExceededException, CssResolutionBudgetExceededException, EncryptionException, FontNotFoundException, FontParsingException, GraphicsStateBalanceException, HtmlParsingException, ImageProcessingException, InvalidConfigException, LinearizationInvariantException, LinearizationUnimplementedException, MissingShadingResourceException, NotImplementedException, PageLayoutException, PdfRViolationException, SignatureException, TemplateException, UnsupportedAlgorithmException, WriterException.

Exemplo de código — Início rápido

Capture qualquer erro do mecanismo capturando o tipo base.

<?php

declare(strict_types=1);

use NextPDF\Core\Document;
use NextPDF\Exception\NextPdfException;

try {
    $doc = Document::createStandalone();
    $doc->addPage();
    $doc->setFont('helvetica', '', 12);
    $doc->cell(0, 10, 'Hello');
    $doc->save('out.pdf');
} catch (NextPdfException $e) {
    \error_log($e->getMessage());
}

O exemplo executável examples/15-exception-handling.php exercita esse padrão.

Exemplo de código — Produção

Faça a recuperação no nível da classe folha e envie o contexto estruturado para o pipeline de logs.

<?php

declare(strict_types=1);

use NextPDF\Contracts\ContextAwareExceptionInterface;
use NextPDF\Core\Document;
use NextPDF\Exception\FontNotFoundException;
use NextPDF\Exception\NextPdfException;
use Psr\Log\LoggerInterface;

function render(Document $doc, LoggerInterface $logger): void
{
    try {
        $doc->setFont('Brand-Sans', '', 12);
        $doc->cell(0, 10, 'Invoice');
        $doc->save('invoice.pdf');
    } catch (FontNotFoundException $e) {
        // Targeted recovery: fall back to a built-in font.
        $logger->warning($e->getMessage(), $e->getContext());
        $doc->setFont('helvetica', '', 12);
        $doc->save('invoice.pdf');
    } catch (NextPdfException $e) {
        // Any other engine error: structured context, then rethrow.
        $context = $e instanceof ContextAwareExceptionInterface
            ? $e->getContext()
            : [];
        $logger->error($e->getMessage(), $context);
        throw $e;
    }
}

Casos extremos e pegadinhas

• A ordem dos catch importa. Liste as classes folha antes de NextPdfException; um catch (NextPdfException) no início captura todas as subclasses.
• getContext() usa chaves em snake_case, e os valores são primitivos ou listas de primitivos, sem objetos aninhados. O payload é seguro para serialização em JavaScript Object Notation (JSON).
• O NextPdfException::getContext() base retorna []. Uma subclasse que não o sobrescreve não carrega campos estruturados. Nesse caso, conte com getMessage().
• NextPdfException é abstrata; você não pode instanciá-la diretamente. Lance uma classe folha concreta.
• NotImplementedException é deliberadamente ruidosa. Ela sinaliza uma implementação intencionalmente ausente, não uma falha transitória. Não a repita.
• Strict\* sinaliza violações que indicam uma quebra de contrato do modo de conformidade, não um erro de runtime recuperável. Trate-as como defeitos de configuração ou de entrada.
• Não há nenhuma constante de código de erro em string. Faça a correspondência pelo tipo da exceção. Encaminhe getContext() para consumidores de máquina.

Desempenho

A construção da exceção faz uma alocação de objeto mais a chamada sprintf que monta a mensagem: O(1). getContext() retorna um pequeno array associativo construído a partir de campos já mantidos: O(1) no número de campos. As exceções são executadas no caminho de falha, não no caminho crítico. O custo é insignificante em comparação com o trabalho que falhou. O performance_budget padrão para esta página de referência é wall_ms: 1500, peak_mb: 64.

Notas de segurança

Os campos de contexto podem carregar detalhes derivados do documento. FontNotFoundException inclui os caminhos de busca do sistema de arquivos, WriterException inclui o caminho de saída e InvalidConfigException inclui o valor fornecido. Antes de encaminhar o contexto para um destino de logs de baixa confiança, limpe os campos ou passe apenas uma allowlist de chaves, pois caminhos e valores podem revelar o layout da implantação ou a entrada do usuário. As mensagens de exceção são legíveis por humanos e podem incluir o mesmo detalhe. Não exiba mensagens brutas aos usuários finais em um contexto sensível à segurança. SignatureException vincula deliberadamente à mensagem a causa-raiz concreta, como um pacote ausente ou um Uniform Resource Locator (URL) vazio para uma Time Stamping Authority (TSA), para que os operadores possam fazer a triagem sem procurar os pontos de chamada. Esse detalhe é voltado para o operador, não para o usuário final.

Conformidade

Este módulo define um modelo de erros do mecanismo e não traz nenhuma citação normativa de norma. As exceções lançadas para violações de normas, por exemplo PdfRViolationException ou Strict\OracleConformanceFailure, referenciam a cláusula aplicável no módulo que detecta a violação, não aqui.

Veja também

• /modules/core/contracts/ — ContextAwareExceptionInterface, definição da interface
• /modules/core/observability/ — encaminhamento de getContext() para o APM
• /modules/core/config/ — InvalidConfigException, NotImplementedException
• /modules/core/support/ — DegradedException; WarningCode (NEXTPDF_W_*)
• /modules/core/event/ — InvalidConfigException de addListener()

Glossário: exceção ciente de contexto · política de degradação