Erreurs du cœur et générales

Portée

Ces entrées couvrent les exceptions du cœur et à usage général que lève NextPDF. La plupart étendent la base NextPdfException, qui elle-même étend \RuntimeException et implémente ContextAwareExceptionInterface. Cette interface expose une seule méthode, getContext(): array, renvoyant une carte plate en snake_case de primitives sûres à sérialiser dans un journal ou une charge utile APM.

Attrape la famille NextPdfException avec un seul catch (NextPdfException $e). Ajoute aussi un catch (\RuntimeException $e) pour couvrir les quelques erreurs de bas niveau de cet ensemble qui étendent directement \RuntimeException (listées ci-dessous). La base NextPdfException::getContext() renvoie un tableau vide ; les sous-classes la redéfinissent pour ajouter des champs de domaine. Lorsqu’une classe ne redéfinit pas getContext(), elle hérite du tableau vide et le détail de diagnostic vit dans le message et les accesseurs typés à la place.

Quatre types de cet ensemble n’étendent pas NextPdfException : BlackPointCompensationUnsupportedException et UnsupportedSourceDocumentException étendent directement \RuntimeException (attrape-les en tant que \RuntimeException), et ComplianceViolation et RuleViolation sont des objets-valeurs, pas des exceptions — ils sont documentés ici parce qu’ils modélisent les données d’erreur et de violation que renvoie le moteur.

Exception de base

NextPdfException

• Ce que c’est. Base abstract de toute exception levée par le cœur de NextPDF et ses paquets d’extension. Elle étend \RuntimeException et implémente ContextAwareExceptionInterface. Attraper ce seul type intercepte n’importe quelle erreur de la bibliothèque.
• Contexte. La base getContext() renvoie un tableau vide. Les sous-classes la redéfinissent pour renvoyer des champs propres au domaine.
• Rétablissement. N’est pas levée directement. Utilise-la comme type fourre-tout ; branche sur la sous-classe concrète pour un traitement spécifique.

Configuration et activation de fonctionnalités

InvalidConfigException

• Quand elle est levée. Lorsqu’une valeur Config ou une combinaison de valeurs est invalide — un réglage requis manquant, une option mutuellement exclusive, ou une valeur hors de la plage acceptée. Cela signale une erreur de développeur : le code appelant a fourni une configuration qui doit être corrigée avant de réessayer. Le message indique la clé, le type ou la plage attendus, et le type de débogage réel de la valeur fournie.
• Contexte. getContext() renvoie config_key, given_value et expected_type. Accesseurs typés : getConfigKey(), getGivenValue(), getExpectedType().
• Rétablissement. Action du développeur : corrige la clé de configuration nommée pour lui donner une valeur du type ou de la plage attendus avant de rappeler NextPDF.

NotImplementedException

• Quand elle est levée. Lorsqu’un point d’entrée d’API publique est atteint mais que son implémentation est intentionnellement absente de la version actuelle. Utilisée pour les cales de compatibilité dépréciées qui existent pour donner aux appelants pré-bisect un échec bruyant et actionnable plutôt qu’un no-op silencieux. Le message combine une étiquette feature recherchable par machine et une référence followUp (identifiant de défaut, ancre de suivi ou nom de sprint).
• Contexte. Ne redéfinit pas getContext(), donc elle renvoie un tableau vide. Les valeurs $feature et $followUp sont des propriétés publiques en lecture seule et sont intégrées dans le message.
• Rétablissement. Action de l’appelant de la bibliothèque : supprime l’appel, ou épingle une version future qui livre le suivi nommé.

IncompatibleFeatureFlagsException

• Quand elle est levée. À la construction du Config (Config::validate()) lorsqu’une combinaison de CssFeatureFlags est incohérente en interne — un indicateur en présuppose un autre qui est désactivé. La seule combinaison interdite aujourd’hui est layoutSubgrid = true avec layoutGrid = false : un axe en subgrid dérive ses lignes de grille d’un conteneur de grille parent (CSS Grid Layout Module Level 2 §1), donc subgrid sans grid décrit une grille qui ne peut pas exister. La vérification s’exécute sur les indicateurs résolus, donc CssRenderingMode::Safe (qui force chaque fonctionnalité Phase 4+ à off) masque la combinaison plutôt que de la déclencher. Étend StrictModeViolation.
• Contexte. getContext() fusionne les champs de mode strict du parent (cssDeviation, excId, chunkSha256, location) avec les booléens layoutGrid et layoutSubgrid. Le location vaut Config::validate() et cssDeviation encode la paire d’indicateurs.
• Rétablissement. Action de l’appelant de la bibliothèque : active layoutGrid en même temps que layoutSubgrid, ou désactive layoutSubgrid.

IncompatibleRenderingModeException

• Quand elle est levée. À la construction du Config lorsqu’un appariement CssRenderingMode et CssLayoutMode tombe en dehors des cellules compatibles de la matrice de modes. Le seul appariement interdit aujourd’hui est CssRenderingMode::Safe + CssLayoutMode::Retained — Safe force chaque fonctionnalité Phase 4+ à off, laissant les contextes de formatage en mode retenu (Grid, Subgrid, @container) sans consommateurs, donc la combinaison est rejetée plutôt que d’être laissée se dégrader silencieusement. Étend StrictModeViolation.
• Contexte. getContext() fusionne les champs de mode strict du parent avec mode1 (la valeur du mode de rendu) et mode2 (la valeur du mode de mise en page). Le cssDeviation encode la paire de modes ; location vaut Config::validate().
• Rétablissement. Action de l’appelant de la bibliothèque : choisis Safe + Streaming pour le retour arrière, ou un mode de rendu non-Safe (Normal / Strict / Audit) avec Retained pour Grid / Subgrid / Container Queries.

StrictModeViolation

• Quand elle est levée. Base abstract de toute exception de déviation par rapport à la spécification, levée sous CssRenderingMode::Strict. En mode strict, toute déviation CSS détectée qui n’est pas liée à une entrée d’exception EXC-NNN enregistrée lève une instance de cette classe (ou d’une sous-classe) au point de détection. N’est pas levée directement ; voir IncompatibleFeatureFlagsException et IncompatibleRenderingModeException.
• Contexte. getContext() renvoie les quatre champs ADR-023 : cssDeviation (étiquette courte de la construction déviante), excId (identifiant de registre lorsqu’enregistré, sinon null), chunkSha256 (hachage du fragment de citation de spécification lorsqu’il est connu, sinon null) et location (origine lisible par l’appelant, sinon null).
• Rétablissement. Action de l’appelant de la bibliothèque : enregistre la déviation en tant que nouvelle entrée EXC-NNN validée, ou corrige le renderer pour supprimer la déviation.

Entrée HTML et CSS

HtmlParsingException

• Quand elle est levée. Lorsque l’analyse de l’entrée HTML ou la construction du DOM échoue : déclarations de charset invalides, violations de la limite de taille d’entrée, profondeur d’imbrication excessive, dépassements du nombre d’éléments et erreurs de structure de table telles qu’un maximum de nombre de lignes. L’épuisement de ressources propre au CSS est signalé à la place par CssParserLimitExceededException et CssResolutionBudgetExceededException.
• Contexte. getContext() renvoie html_snippet (un extrait court et tronqué du HTML fautif), position (décalage en octets, ou -1 si inconnu) et rule (la contrainte d’analyseur violée). Accesseurs typés : getHtmlSnippet(), getPosition(), getRule().
• Rétablissement. Action du développeur : simplifie l’entrée HTML ou ajuste les limites de l’analyseur.

CssParserLimitExceededException

• Quand elle est levée. Lorsque l’entrée CSS dépasse une limite de sécurité configurée de l’analyseur. Deux catégories sont couvertes via les constructeurs nommés : forByteLimit() (feuille de style trop grande pour un traitement par regex sûr) et forNestingDepth() (récursion d’imbrication CSS trop profonde). Les deux messages nomment la valeur réelle et la limite.
• Contexte. getContext() renvoie limit_type (byte ou nesting_depth), actual et limit.
• Rétablissement. Action du développeur : scinde la feuille de style en feuilles plus petites, réduis la profondeur d’imbrication, ou relève la limite configurée.

CssResolutionBudgetExceededException

• Quand elle est levée. Lorsque la résolution CSS :has() dépasse son budget de parcours. Le résolveur :has() en deux passes applique un budget strict de visites de nœuds pour empêcher des sélecteurs pathologiques de provoquer des parcours quadratiques du document ; dès que le nombre total de visites dépasse la limite, la feuille de style est rejetée comme trop complexe. Le message nomme le nombre de visites et le budget.
• Contexte. getContext() renvoie visits et budget. Accesseurs typés : getVisits(), getBudget().
• Rétablissement. Action du développeur : réduis la complexité des sélecteurs, ou relève le budget configuré.

Polices et images

FontNotFoundException

• Quand elle est levée. Lorsqu’un fichier de police ne peut pas être localisé ou lu au niveau du système de fichiers : la famille ou le chemin demandé n’existe pas, n’est pas lisible, ou le répertoire de polices configuré est inaccessible. Les données de police peuvent être valides — cela signale seulement qu’elles ne peuvent pas être atteintes. Le message liste les chemins recherchés.
• Contexte. getContext() renvoie font_name, search_paths (une liste) et fallback_attempted (un booléen). Accesseurs typés : getFontName(), getSearchPaths(), wasFallbackAttempted().
• Rétablissement. Action du développeur : vérifie le chemin de la police. Action d’infrastructure : corrige les permissions de fichier sur le fichier ou le répertoire de police.

FontParsingException

• Quand elle est levée. Lorsqu’un fichier de police est trouvé mais que son contenu n’est pas utilisable : il est corrompu, dans un format non pris en charge, ou il manque des tables requises. Couvre les échecs de validation structurelle pendant l’analyse TrueType, Type 1, CFF et OpenType — en-têtes tronqués, répertoires de tables invalides, tables obligatoires manquantes (head, hhea, OS/2), erreurs de dépaquetage et violations de taille. Le message nomme le fichier et l’erreur d’analyse.
• Contexte. getContext() renvoie font_file et parse_error. Accesseurs typés : getFontFile(), getParseError().
• Rétablissement. Action du développeur : remplace le fichier de police par un fichier valide.

ImageProcessingException

• Quand elle est levée. Lorsqu’une image ne peut pas être décodée, est dans un format non pris en charge, ou échoue au traitement GD/Imagick : octets magiques non reconnaissables, données JPEG corrompues, types MIME non pris en charge, violations de la limite de taille de fichier et échecs d’allocation de ressource GD. L’image était accessible mais ses données de pixels n’ont pas pu être extraites pour l’incorporation.
• Contexte. getContext() renvoie image_path (vide pour des données inline), format (détecté ou attendu, p. ex. jpeg, png, unknown) et operation (p. ex. decode, resize, embed). Accesseurs typés : getImagePath(), getFormat(), getOperation().
• Rétablissement. Action du développeur : fournis un fichier image valide et pris en charge.

Sortie, mise en page et sérialisation

CompressionException

• Quand elle est levée. Lorsque la compression ou la décompression FlateDecode (zlib) échoue — échecs de gzcompress/gzuncompress sur les flux de contenu, les données de police, le contenu de page, les données de pièce jointe et les flux de référence croisée. Typiquement un flux d’entrée corrompu, une mémoire insuffisante, ou une extension zlib manquante.
• Contexte. getContext() renvoie algorithm (nom du filtre, p. ex. FlateDecode, LZWDecode) et stream_length (longueur en octets, ou -1 si inconnue). Accesseurs typés : getAlgorithm(), getStreamLength().
• Rétablissement. Action d’infrastructure : vérifie que ext-zlib est chargée et que la mémoire est suffisante.

WriterException

• Quand elle est levée. Lorsque la sérialisation PDF, la linéarisation ou la sortie d’E/S échoue : erreurs d’écriture de flux de PdfWriter, corruption de la table de référence croisée, échecs de génération d’en-tête/de fin de fichier, échecs de résolution de référence d’objet, erreurs d’écriture de fichier et débordements du tampon de sortie. Un document en mémoire valide n’a pas pu être sérialisé en un flux d’octets valide. Le message nomme l’étape.
• Contexte. getContext() renvoie output_path (vide pour une sortie en chaîne) et writer_state (l’étape, p. ex. header, body, xref, trailer). Accesseurs typés : getOutputPath(), getWriterState().
• Rétablissement. Action d’infrastructure : vérifie l’espace disque, les permissions de fichier et le flux de sortie.

PageLayoutException

• Quand elle est levée. Lorsque les contraintes de mise en page ne peuvent pas être satisfaites : violations de mise en page en colonnes (largeur insuffisante, nombre de colonnes invalide), débordement de contenu au-delà des bordures de page et conflits de marges. La mise en page demandée est géométriquement impossible pour les dimensions de page et le contenu donnés. Le message nomme le numéro de page lorsqu’il est connu et la contrainte violée.
• Contexte. getContext() renvoie page_number (à base 1, ou 0 si inconnu) et constraint. Accesseurs typés : getPageNumber(), getConstraint().
• Rétablissement. Action du développeur : ajuste la taille de page, les marges, les réglages de colonnes ou le contenu.

TemplateException

• Quand elle est levée. Lorsqu’une opération d’import ou de réutilisation de modèle PDF échoue dans TemplateManager : transitions d’état de modèle invalides (début ou fin de modèles hors séquence), référence à un modèle inexistant et échecs de compression de flux lors de la sérialisation du modèle. Le message nomme l’opération et l’identifiant de modèle lorsqu’il est attribué.
• Contexte. getContext() renvoie template_id (vide s’il n’est pas encore attribué) et operation (p. ex. begin, end, use, serialize). Accesseurs typés : getTemplateId(), getOperation().
• Rétablissement. Action du développeur : corrige la séquence d’utilisation du modèle ou le PDF source.

Invariants du flux de contenu

ContentStreamBalanceException

• Quand elle est levée. Lorsqu’un ContentStreamBuilder détecte une paire d’opérateurs déséquilibrée à la fermeture du flux (ou en cours de flux lorsque les invariants sont vérifiés avec empressement). Elle capture les compteurs de profondeur qui ont échoué à l’invariant d’équilibre afin que la journalisation puisse identifier quel émetteur a laissé fuir un q, BT ou BMC sans son Q, ET ou EMC correspondant. Selon ISO 32000-2:2020 §8.4.2 (pile d’état graphique), §9.4.1 (objets texte) et §14.6 (contenu marqué).
• Contexte. getContext() renvoie graphics_depth, text_block_depth, marked_content_depth et offending_operator. Accesseurs typés : getGraphicsDepth(), getTextBlockDepth(), getMarkedContentDepth(), getOffendingOperator().
• Rétablissement. Action du développeur : localise l’émetteur qui a ouvert une construction sans la fermer.

GraphicsStateBalanceException

• Quand elle est levée. Lorsqu’un flux de contenu PDF se ferme avec des opérateurs q/Q déséquilibrés. ISO 32000-2:2020 §8.4.2 exige que chaque sauvegarde d’état graphique (q) soit appariée à exactement une restauration (Q) avant la fin du flux ; un déséquilibre laisse fuir la transformation, le chemin de découpe, les couleurs et l’intention de rendu vers les pages suivantes ou les Form XObjects. Levée uniquement lorsque la vérification stricte de l’état graphique est activée (NEXTPDF_GFXSTATE_STRICT=1) ; en mode relâché, un avertissement est émis via trigger_error() à la place.
• Contexte. getContext() renvoie save_depth (positif pour trop de sauvegardes, négatif pour trop de restaurations). Accesseur typé : getSaveDepth().
• Rétablissement. Action du développeur : localise la paire save()/restore() non appariée.

MissingShadingResourceException

• Quand elle est levée. Lorsque ConicGradientRenderer::render() est invoqué sans contexte de registre de ressources Shading. Le changement cassant de la v10.0.0 a supprimé l’ancien chemin de substitution par carte de marqueurs implicite : les appelants doivent construire le renderer avec un ShadingResourceRegistryInterface afin que l’objet indirect /ShadingType 4 soit enregistré dans le sous-dictionnaire de ressources Shading de la page (ISO 32000-2 §8.7.4.2 / §8.7.4.3). Le message nomme le contexte de l’appelant et pointe vers la note de migration v9.x→v10.0.
• Contexte. getContext() renvoie context (une étiquette courte de contexte d’appelant, p. ex. ConicGradientRenderer::render).
• Rétablissement. Action de l’appelant de la bibliothèque : câble une instance de registre de ressources Shading dans le constructeur du renderer avant d’appeler render().

Linéarisation (Fast Web View)

LinearizationInvariantException

• Quand elle est levée. Lorsque le Linearizer v2 à trois passes détecte que ses assertions MEASURE → PLACE → FILL ont été violées : un nombre d’octets de la passe 3 ne correspondant pas à la longueur de fichier prédite par la passe 1 (dérive de décalage), un emplacement réservé du dictionnaire de linéarisation trop petit pour la largeur sérialisée, ou un décalage de flux d’indices /H [offset length] ne correspondant pas à la sortie finale. Faire remonter cela plutôt que d’émettre un PDF cassé est une garantie de sécurité affichée.
• Contexte. getContext() renvoie invariant (le nom de l’invariant violé), expected, actual et delta (la différence signée). Accesseurs typés : getInvariant(), getExpectedValue(), getActualValue().
• Rétablissement. Action du mainteneur : ouvre un rapport de bug — ces invariants devraient tenir pour toutes les entrées bien formées. Capture l’exception précédente chaînée.

LinearizationUnimplementedException

• Quand elle est levée. Lorsque l’indicateur de fonctionnalité du linéariseur est réglé sur un backend intentionnellement désactivé. Actuellement levée uniquement pour linearizerVersion === 'v1-noop', le réglage de rétrogradation d’urgence qui rejette toutes les tentatives de linéarisation à l’exécution sans changement de code ni redéploiement — utile pour couper Fast Web View en production.
• Contexte. getContext() renvoie reason (une explication courte lisible par un humain). Accesseur typé : getReason().
• Rétablissement. Action de l’opérateur / de l’ingénierie de release : ajuste la configuration ou mets à niveau vers une version de backend corrigée.

Invariants de conformité et de profil

ConformanceViolationException

• Quand elle est levée. Lorsqu’une fonctionnalité demandée ne peut pas être émise sans rompre le contrat de conformité ISO déclaré du document, et que le moteur échoue en mode fermé plutôt que d’écrire un objet non conforme. Le déclencheur canonique est une annotation multimédia Screen ou une action Rendition (ISO 32000-2:2020 §12.5.6.18 / §13.2) sous un profil d’archivage PDF/A, ce que chaque partie de PDF/A interdit (série ISO 19005) — le fichier échouerait à la validation veraPDF, donc le moteur refuse d’emblée.
• Contexte. getContext() renvoie conformance_mode (le mode déclaré, p. ex. pdfa4) et feature (la fonctionnalité rejetée, p. ex. Screen annotation). Les deux sont des propriétés publiques en lecture seule. La raison est le message de l’exception.
• Rétablissement. Action du développeur : abandonne l’appel multimédia pour une sortie d’archivage, ou cible un profil de conformité non archivistique (par défaut ConformanceMode::Plain).

PdfRViolationException

• Quand elle est levée. Lorsqu’un invariant de conformité PDF/R-1 (ISO 23504-1:2020) est violé, soit à la construction d’un objet-valeur (les profils PdfRStrip, PdfRPage, PdfRDocument), soit au moment du validateur (PdfRValidator). Elle capture la clause normative fautive et une description de violation sur une ligne afin que les consommateurs d’audit puissent router les constats vers la bonne sous-clause §6 sans analyser du texte libre.
• Contexte. getContext() renvoie standard (toujours ISO 23504-1:2020), clause (le chemin de clause, p. ex. 6.6.1) et violation. Accesseurs typés : getClause(), getViolation().
• Rétablissement. Action du développeur : corrige l’entrée rejetée ou reconstruis le document pour qu’il soit conforme à la clause citée.

Génération de codes-barres

BarcodeException

• Quand elle est levée. Lorsque la génération de code-barres échoue à cause de données invalides ou d’erreurs d’encodage à travers toutes les symbologies prises en charge (Code 39/128, UPC-A/E, EAN-8/13, Interleaved/Standard 2-of-5, POSTNET, PLANET, MSI, ISBN, ISSN, QR Code, PDF417, DataMatrix, JabCode), et d’échecs de rendu GD lors de la création de l’image. La valeur du code-barres est plafonnée à un extrait de 128 octets dans le message et le contexte — les charges utiles trop longues ou binaires sont stockées tronquées avec un marqueur ... (<N> bytes, truncated) afin de ne pas pouvoir être copiées en entier dans un journal.
• Contexte. getContext() renvoie barcode_type (symbologie, p. ex. QRCODE, EAN13, CODE128) et value (la valeur tronquée). Accesseurs typés : getBarcodeType(), getValue().
• Rétablissement. Action du développeur : corrige les données du code-barres ou la sélection de symbologie.

BarcodeEncoderNotFoundException

• Quand elle est levée. Depuis BarcodeEncoderRegistry lorsque le type d’encodeur demandé est inconnu ou que sa porte de capacité est fermée. Elle implémente aussi PSR-11 Psr\Container\NotFoundExceptionInterface, donc le registre est un conteneur conforme aux standards. Le message nomme la symbologie et la raison.
• Contexte. Ne redéfinit pas getContext(), donc elle renvoie un tableau vide. Les valeurs type et reason sont disponibles via les accesseurs getType() et getReason() et dans le message.
• Rétablissement. Action du développeur : enregistre l’encodeur, ou installe le paquet qui le fournit (par exemple nextpdf/pro pour Micro QR / DotCode / HanXin / JabCode).

Cryptographie, chiffrement et signatures

EncryptionException

• Quand elle est levée. Lorsque le chiffrement ou le déchiffrement PDF échoue : échecs de chiffrement/déchiffrement AES-256-CBC, erreurs OpenSSL, tailles d’IV invalides, échecs de calcul de hachage et erreurs de calcul de valeur UE/OE. Typiquement une extension OpenSSL manquante ou mal configurée, un matériel de clé invalide, ou des données chiffrées corrompues. Le message nomme l’opération et l’algorithme.
• Contexte. getContext() renvoie algorithm (p. ex. AES-256-CBC) et operation (p. ex. encrypt, decrypt, key_derivation). Accesseurs typés : getAlgorithm(), getOperation().
• Rétablissement. Action d’infrastructure : assure-toi qu’OpenSSL est disponible et correctement configuré. Voir Chiffrement et permissions.

UnsupportedAlgorithmException

• Quand elle est levée. Lorsqu’un algorithme cryptographique ne peut pas être exécuté dans l’environnement d’exécution actuel : une extension PHP requise est indisponible, la bibliothèque sous-jacente manque la primitive, l’extension hash empaquetée ne peut pas synthétiser une variante SHAKE/XOF, ou l’algorithme n’est pas enregistré dans le SignatureAlgorithmRegistry. Le moteur ne doit pas se dégrader silencieusement vers une primitive plus faible, donc il fait remonter ceci à la place. La fabrique statique nonFipsHostUnderFipsProfile() la lève (avec l’identifiant d’algorithme regulatory-profile:fips) lorsque RegulatoryProfile::FIPS est sélectionné mais qu’un fournisseur OpenSSL validé FIPS ne peut pas être confirmé (à la fois FIPS_ABSENT et INDETERMINATE échouent en mode fermé).
• Contexte. getContext() renvoie algorithm (nom ou OID, p. ex. shake256, Ed25519, AES-256-GCM) et reason (actionnable par l’opérateur). Accesseurs typés : getAlgorithm(), getReason().
• Rétablissement. Action de l’opérateur : installe l’extension manquante ou mets à niveau l’environnement d’exécution ; pour la porte FIPS, installe une build OpenSSL validée FIPS ou règle NEXTPDF_FIPS_MODE explicitement. Action du développeur : enregistre un descripteur d’algorithme personnalisé via SignatureAlgorithmRegistry::register().

SignatureException

• Quand elle est levée. Lorsqu’une opération de signature numérique échoue : gestion de certificat et de clé privée (analyse PKCS#12, décodage PEM/DER, validation X.509), construction PKCS#7/CMS, format de signature ECDSA, violations de taille de conteneur, encodage DER et orchestration PAdES. Les erreurs propres à la TSA sont signalées à la place par la TsaException plus spécifique. Préfère les fabriques nommées typées au constructeur positionnel ; chacune lie la cause racine à la fin du message. Exemples : ltvCapabilityMissing() (B-LT/B-LTA nécessite nextpdf/enterprise), tsaRequired() / tsaUrlEmpty() / tsaEmptyToken(), httpClientMissing(), hsmSignerMissing() / hsmSignatureEmpty(), signatureContentsNotFound() / signatureContentsPaddingCorrupt(), unexpectedKeyType(), pemDecodingFailed(), la famille Ed25519 (ed25519SignatureMalformed(), ed25519RoundTripVerifyFailed(), ed25519KeyParseFailed(), ed25519SeedInvalid(), ed25519SecretKeyMalformed(), ed25519PublicKeyInvalid()), documentTimestampNotEmitted(), algorithmPolicyRejected(), digestOnlyAlgorithmRefused(), encryptedLtvUnsupported(), incrementalUpdateWriterMissing(), et la paire de statut OCSP nonSuccessfulOcspResponseStatus() / reservedOcspResponseStatus() (RFC 6960 §4.2.1). Ces fabriques échouent en mode fermé plutôt que d’émettre une signature silencieusement rétrogradée.
• Contexte. getContext() renvoie cert_info (DN du sujet ou empreinte, ou vide), signature_level (le niveau PAdES tenté, p. ex. B-B, B-T, B-LT, B-LTA) et detail (le diagnostic actionnable, vide pour le constructeur positionnel hérité). Accesseurs typés : getCertInfo(), getSignatureLevel(), getDetail().
• Rétablissement. Action du développeur : corrige la configuration du certificat/de la clé. Pour les fabriques de capacité manquante, installe le paquet nommé. Voir Échecs de signature et d’horodatage pour les entrées symptôme-résolution par fabrique.

BlackPointCompensationUnsupportedException

• Quand elle est levée. Depuis NullBlackPointCompensationTransform::transform() lorsqu’un appelant demande à l’adaptateur nul d’appliquer une transformation de compensation du point noir ISO 18619 non-Default. L’adaptateur nul est le repli sûr pour les environnements sans backend de gestion des couleurs ; produire un échantillon transformé sans un vrai module de gestion des couleurs signalerait silencieusement une conversion erronée. Contrairement à la plupart des entrées ici, celle-ci étend directement \RuntimeException, pas NextPdfException, donc les chemins catch (\RuntimeException) existants continuent de fonctionner.
• Contexte. Pas de getContext() ; c’est une simple \RuntimeException. Le détail est dans le message.
• Rétablissement. Action du développeur : enregistre une vraie BlackPointCompensationTransform (LittleCMS, Argyll, pur PHP), ou restreins /UseBlackPtComp à BlackPointCompensation::Default.

Assemblage de document et accessibilité

UnsupportedSourceDocumentException

• Quand elle est levée. Lorsqu’un document source ne peut pas être copié en toute sécurité dans une sortie de fusion/scission et que l’opération échoue en mode fermé plutôt que d’émettre un résultat corrompu ou compromis sur le plan de la sécurité. Utilise les fabriques nommées : encrypted() (ISO 32000-2 §7.6 — le contenu ne peut pas être copié sans la clé), signed() (§12.8 — copier des pages invaliderait la plage d’octets de la signature), unsupportedStreamFilter() (un filtre que le lecteur de graphe d’objets ne peut pas reproduire à l’identique), multipleInteractiveForms() (une limitation documentée : plus d’une source porte un /AcroForm non vide, §12.7) et splitWithInteractiveForm() (une limitation documentée : sous-ensembler les pages d’une source porteuse de formulaire orphelinerait les widgets). Étend directement \RuntimeException, pas NextPdfException.
• Contexte. Pas de getContext() ; c’est une simple \RuntimeException. La cause et le numéro d’objet affecté sont nommés dans le message.
• Rétablissement. Action du développeur : déchiffre d’abord la source ou fournis la clé ; pour les sources signées, signe après la fusion à la place ; pour les fusions multi-formulaires, aplatis ou supprime les champs de formulaire de toutes les sources sauf une ; pour les scissions de sources porteuses de formulaire, aplatis le formulaire avant la scission.

InvalidBcp47TagException

• Quand elle est levée. Depuis Bcp47Validator::validate() lorsqu’une étiquette de langue candidate est malformée selon l’ABNF RFC 5646 §2.1, ou échoue à la recherche dans le registre organisé. Propre à BCP-47 / ISO 14289-2:2024 §8.4.4, distincte d’InvalidConfigException afin que les appelants en aval de la couture d’accessibilité puissent attraper un type étroit. La paire de prédicats Bcp47Validator::isWellFormed() / isValid() reste la surface de valeur de retour rétrocompatible pour les appelants qui préfèrent brancher plutôt que de recourir aux exceptions.
• Contexte. getContext() renvoie tag (le candidat exactement tel que fourni) et reason (un code de rejet stable lisible par machine, p. ex. empty-string, well-formed-shape, unregistered-primary, duplicate-variant). Accesseurs typés : getTag(), getReason().
• Rétablissement. Action du développeur : corrige l’étiquette de langue pour en faire une étiquette BCP-47 bien formée et enregistrée. Voir Polices et balisage.

FormFieldAccessibilityException

• Quand elle est levée. Lorsqu’un champ de formulaire interactif s’appuierait sur un nom accessible synthétique (non fourni par l’auteur) tout en produisant un document PDF/UA avec l’application stricte du nom de champ accessible activée. La sortie PDF/UA par défaut émet un nom de repli synthétique dans le /Contents du widget afin qu’un champ ne soit jamais sans nom ; le mode strict exige plutôt que l’auteur fournisse un nom significatif (une infobulle, ou une légende pour un bouton-poussoir sans action) afin que les utilisateurs de lecteur d’écran obtiennent une vraie description (ISO 14289-2:2024 §8.10.2).
• Contexte. Ne redéfinit pas getContext(), donc elle renvoie un tableau vide. Le $fieldId est une propriété publique en lecture seule ; la raison est le message.
• Rétablissement. Action du développeur : fournis une infobulle / un nom accessible pour le champ nommé avant de produire un document PDF/UA strict, ou désactive le mode strict. Voir Validation PDF/A et PDF/UA.

VendorExtensionRegistryConflictException

• Quand elle est levée. Depuis VendorExtensionRegistry::register() lorsqu’un appelant réenregistre un préfixe de fournisseur d’extension-développeur PDF connu (ISO 32000-2:2020 §7.12.1) avec une description qui contredit les métadonnées déjà enregistrées. Les descripteurs sont en ajout seul et à détection de conflit ; l’exception typée a remplacé une \RuntimeException générique afin que les appelants puissent attraper cette classe spécifique.
• Contexte. getContext() renvoie prefix, existing_description et attempted_description. Accesseurs typés : getPrefix(), getExistingDescription(), getAttemptedDescription().
• Rétablissement. Action du développeur : enregistre le préfixe avec la description existante, ou utilise un préfixe distinct ; n’écrase pas les métadonnées enregistrées.

Export d’audit

AuditExportException

• Quand elle est levée. Lorsque l’assemblage du paquet d’export d’audit, la génération de la matrice de traçabilité ou la projection de schéma échoue à l’exécution. Couvre les E/S sur claims.json / manifest.json, l’encodage/le décodage JSON du paquet canonique et le décalage de version de schéma sur le chemin de rétrocompatibilité AuditExporter::projectToV1(). Le message nomme l’étape, l’artefact lorsqu’il est connu et le détail.
• Contexte. getContext() renvoie stage (p. ex. read_claims, encode_bundle, project_v1), detail et artefact (le chemin ou la schema_version qui a déclenché l’échec). Accesseurs typés : getStage(), getDetail(), getArtefact().
• Rétablissement. Action de conformité / DevOps : vérifie les chemins des artefacts d’entrée, régénère claims.json à partir d’une exécution propre, ou reconstruis le manifeste avant de retenter l’export.

Objets-valeurs de violation

Ce ne sont pas des exceptions. Ce sont des objets-valeurs immuables que le moteur renvoie pour décrire une violation individuelle ; ils ne portent pas de getContext().

ComplianceViolation

• Ce que c’est. Un objet-valeur final readonly représentant un échec de règle unique signalé par un validateur externe (veraPDF ou équivalent), incluant la référence de clause ISO et l’emplacement dans la structure du PDF.
• Champs. Propriétés publiques en lecture seule : ruleId (identifiant de règle du validateur, p. ex. 6.1.2-1), clause (référence de clause ISO, p. ex. ISO 19005-1:2005, 6.1.2), severity (p. ex. error, warning), location (chemin d’objet dans la structure du PDF) et message (description lisible par un humain).
• Utilisation. Inspecte la collection renvoyée par un validateur de conformité ; route ou affiche chaque entrée selon severity et clause. Voir Validation PDF/A et PDF/UA.

RuleViolation

• Ce que c’est. Un objet-valeur final readonly représentant une violation de règle métier Schematron / EN 16931, renvoyée par SchematronRunnerInterface::runRules() et agrégée dans ValidationResult::$ruleViolations. La stabilité est expérimentale.
• Champs. Propriétés publiques en lecture seule : ruleId (identifiant EN 16931 tel que BR-{n}, BR-CO-{n}, BR-CL-{n}, BR-DEC-{n}, ou un pack propre à un palier), severity (une énumération RuleSeverity), message (texte de la règle, en-GB), xpath (XPath dans le XML embarqué, null pour les règles à l’échelle du document) et semanticPath (chemin BG/BT en notation par points tel que BG-22.BT-106, null pour les violations structurelles).
• Utilisation. Inspecte la collection sur le résultat de validation ; route ou affiche chaque entrée selon severity, ruleId et le localisateur.

Voir aussi

• Index de la référence des erreurs
• Index de la base de connaissances
• Échecs de signature et d’horodatage
• Chiffrement et permissions
• Polices et balisage
• Validation PDF/A et PDF/UA