Riferimento degli errori

Questo è l’elenco di riferimento delle eccezioni sollevate da NextPDF Core, organizzato per area. Ogni pagina di categoria documenta, per ciascuna classe, quando viene sollevata, i dati strutturati che trasporta e come effettuare il recupero. Se si sta diagnosticando un sintomo anziché intercettando una classe specifica, conviene iniziare invece dalle guide alla risoluzione dei problemi — sono organizzate in base a ciò che si osserva.

In breve

• La maggior parte delle eccezioni estende un’unica base, NextPdfException, così da poter intercettare l’intera famiglia con un solo blocco catch.
• NextPdfException è context-aware: implementa ContextAwareExceptionInterface, che dichiara getContext(): array. Molte sottoclassi sovrascrivono getContext() per restituire chiavi diagnostiche strutturate; altre ereditano il valore predefinito vuoto ed espongono il dettaglio tramite il messaggio e i getter tipizzati.
• Un numero ristretto di eccezioni di basso livello estende direttamente la \RuntimeException di PHP anziché NextPdfException. Queste non sono context-aware e trasportano il dettaglio su proprietà pubbliche readonly. Ogni pagina di categoria le segnala esplicitamente.
• Due tipi di conformità denominati …Violation (ComplianceViolation, RuleViolation) sono value object, non eccezioni — descrivono un riscontro senza essere sollevati.

Il tipo base e il contratto del contesto

NextPdfException è una classe astratta che estende \RuntimeException e implementa ContextAwareExceptionInterface. Il contratto è ridotto:

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

Un gestore difensivo si presenta quindi così:

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

Poiché alcuni guasti emergono come una \RuntimeException nuda (vedere le note per categoria), un confine a doppia protezione può anche intercettare \RuntimeException e ispezionare il tipo concreto.

Categorie

• Errori core e generali — guasti relativi a documento, unione, accessibilità, fatturazione elettronica, spazio colore, value object e modalità strict, oltre ai tipi base condivisi.
• Errori di sicurezza, firma e PKI — creazione e verifica delle firme, marche temporali, convalida del percorso PKI e dei vincoli sui nomi, hashing, integrità e PKCS#11.
• Errori di rendering e I/O — layout HTML e paged media, font e shaping del testo, writer e reader e metadati XMP.
• Errori di runtime e supporto — trasporto HTTP, resilienza (circuit breaker, modalità degradata), osservabilità e gestione del manifest.
• Errori dell’Accelerator — il trasporto del sidecar di accelerazione opzionale.
• Errori di conformità — requisiti di clause-hash e ciclo di vita della conformità.

Vedere anche

• Risoluzione dei problemi — guide organizzate per sintomo per convalida della firma, cifratura e permessi, font e tagging e convalida PDF/A e PDF/UA.