Base de connaissances pour le dépannage

Ce que couvre cette base de connaissances

Cette base de connaissances relie les échecs observés à leur cause et à leur résolution. Chaque fiche s’appuie sur les classes d’exceptions du moteur, ses tests couvrant les chemins d’échec et ses conditions de garde dans le code source — pas sur des suppositions. Si le moteur n’a aucun chemin de code qui produit un échec donné, cette base de connaissances n’en invente pas.

La base de connaissances comporte quatre pages thématiques :

• Validation de signature — signature invalide, chaîne incomplète, révocation inconnue et échecs d’horodatage.
• Validation PDF/A et PDF/UA — intention de sortie manquante, contenu non balisé, langue manquante, échecs de police embarquée.
• Polices et balisage — police introuvable, sous-ensemble de glyphes, couverture CJK et problèmes d’arbre de structure.
• Chiffrement et permissions — échecs de déchiffrement et limite des indicateurs de permission.

Comment lire une fiche

Chaque fiche comporte cinq parties :

1. Symptôme — ce que tu observes : une classe d’exception, un fragment de message ou le verdict d’un validateur en aval.
2. Cause probable — la condition, dans ton entrée ou ta configuration, que le moteur signale.
3. Preuve / diagnostic — comment confirmer la cause. Cette partie nomme la classe d’exception exacte, le champ getContext() ou le test qui démontre le comportement, pour que tu puisses vérifier au lieu de deviner.
4. Résolution — les étapes à suivre pour supprimer la cause, rédigées comme une procédure ordonnée.
5. Connexe — la page de référence du module ou la fiche voisine à consulter ensuite.

Identifier un échec par type d’exception

NextPDF identifie une erreur par sa classe PHP, pas par un code d’erreur sous forme de chaîne. Il n’existe aucune constante NPDF-#### dans les classes d’exceptions. Capture l’exception feuille pour obtenir une réponse ciblée, et lis ContextAwareExceptionInterface::getContext() pour récupérer des champs de diagnostic structurés. Le type de base est NextPDF\Exception\NextPdfException ; les échecs de sécurité utilisent en plus NextPDF\Security\Exception\SecurityException.

Pour la hiérarchie complète et les règles d’ordre de capture, lis la référence des exceptions.

<?php

declare(strict_types=1);

use NextPDF\Exception\NextPdfException;
use NextPDF\Contracts\ContextAwareExceptionInterface;

try {
    // ... engine call ...
} catch (NextPdfException $e) {
    $context = $e instanceof ContextAwareExceptionInterface
        ? $e->getContext()
        : [];
    \error_log($e->getMessage());
    // $context carries snake_case primitive fields safe to serialize.
}

Portée et limites

Cette base de connaissances décrit la détection et le signalement des échecs à l’intérieur du moteur. Elle ne décrit pas le verdict de conformité rendu par un validateur externe tel que veraPDF ou callas ; ces outils appliquent leurs propres jeux de règles. Lorsque le moteur refuse une opération pour maintenir un document dans un profil — par exemple, en refusant le chiffrement sous PDF/A — la fiche concernée cite la clause directrice et l’exception qui l’applique.

Voir aussi

• Référence des exceptions — hiérarchie complète, ordre de capture, getContext() et son contrat associé
• Référence de conformité — vérificateurs de profils PDF/A, PDF/UA, PDF/X

Glossaire : exception contextuelle