Référence des erreurs

Voici la liste de référence des exceptions que lève NextPDF Core, organisée par domaine. Chaque page de catégorie documente, classe par classe, quand l’exception est levée, les données structurées qu’elle porte et comment se rétablir. Si tu diagnostiques un symptôme plutôt que d’attraper une classe précise, commence plutôt par les guides de dépannage — ils sont organisés selon ce que tu observes.

En bref

• La plupart des exceptions étendent une base unique, NextPdfException, ce qui te permet d’attraper toute la famille avec un seul bloc catch.
• NextPdfException est sensible au contexte : elle implémente ContextAwareExceptionInterface, qui déclare getContext(): array. De nombreuses sous-classes redéfinissent getContext() pour renvoyer des clés de diagnostic structurées ; d’autres héritent de la valeur par défaut vide et exposent leurs détails via le message et des accesseurs typés.
• Un petit nombre d’exceptions de bas niveau étendent directement la \RuntimeException de PHP plutôt que NextPdfException. Celles-ci ne sont pas sensibles au contexte et portent leurs détails sur des propriétés publiques en lecture seule. Chaque page de catégorie les signale explicitement.
• Deux types de conformité nommés …Violation (ComplianceViolation, RuleViolation) sont des objets-valeurs, pas des exceptions — ils décrivent un constat sans être levés.

Le type de base et le contrat de contexte

NextPdfException est une classe abstraite qui étend \RuntimeException et implémente ContextAwareExceptionInterface. Le contrat est minimal :

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

Un gestionnaire défensif ressemble donc à ceci :

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

Parce que certaines défaillances remontent sous la forme d’une \RuntimeException nue (voir les notes par catégorie), une frontière prudente peut aussi attraper \RuntimeException et inspecter le type concret.

Catégories

• Erreurs du cœur et générales — échecs de document, de fusion, d’accessibilité, de facture électronique, d’espace colorimétrique, d’objet-valeur et de mode strict, ainsi que les types de base partagés.
• Erreurs de sécurité, de signature et de PKI — création et vérification de signature, horodatages, validation de chemin PKI et de contraintes de nom, hachage, intégrité et PKCS#11.
• Erreurs de rendu et d’E/S — mise en page HTML et paged-media, polices et façonnage du texte, le writer et le reader, et les métadonnées XMP.
• Erreurs d’exécution et de support — transport HTTP, résilience (disjoncteur, mode dégradé), observabilité et gestion du manifeste.
• Erreurs de l’Accelerator — le transport du sidecar d’accélération optionnel.
• Erreurs de conformité — exigences de hachage de clause et cycle de vie de la conformité.

Voir aussi

• Dépannage — guides organisés par symptôme pour la validation de signature, le chiffrement et les permissions, les polices et le balisage, et la validation PDF/A et PDF/UA.