Erreurs de rendu et d’E/S

Portée

Ces entrées couvrent les exceptions de rendu et d’entrée/sortie (E/S) levées pendant que le pipeline HTML met le contenu en page, que le résolveur paged-media assigne la géométrie de page, que le façonneur de texte traite les écritures complexes, que l’étape de typographie casse les lignes, que le writer sérialise un document, que le reader analyse un PDF existant, et que l’étape de métadonnées lit un paquet Extensible Metadata Platform (XMP).

Deux hiérarchies de base apparaissent ci-dessous, et la différence régit quelles données de diagnostic tu peux lire après un catch :

NextPdfException implémente ContextAwareExceptionInterface::getContext(): array. L’implémentation de base renvoie un tableau vide ; une sous-classe ne porte des clés structurées que lorsqu’elle redéfinit getContext(). Les sous-classes qui ne la redéfinissent pas exposent tout de même leurs données via des propriétés public readonly.
Plusieurs classes ici étendent directement la RuntimeException de PHP. Elles ne sont pas sensibles au contexte et n’ont pas de méthode getContext() ; lis plutôt leur getMessage() et toute propriété publique.

Chaque entrée nomme la classe exacte, la condition de déclenchement, les clés de contexte ou les propriétés publiques qu’elle porte, et le chemin de rétablissement.

Mise en page HTML et paged media

`UnsplittableContentException`

Quand elle est levée. Le moteur de mise en page HTML la lève lorsqu’un contenu marqué break-inside: avoid (une cellule de table dont la contrainte de saut est Avoid) a une hauteur mesurée qui dépasse la hauteur utilisable d’une seule page. Le moteur ne peut pas satisfaire à la fois la contrainte d’évitement de saut et la bordure de page, donc il échoue plutôt que de déborder silencieusement.
Données portées. Étend NextPdfException mais ne redéfinit pas getContext(), donc getContext() renvoie un tableau vide. Les données de diagnostic sont sur des propriétés public readonly : gridRow (int), gridCol (int), contentHeight (float, points) et pageHeight (float, points). Le message nomme les coordonnées de la cellule et les deux hauteurs.
Rétablissement. Supprime la contrainte break-inside: avoid sur la cellule fautive, réduis le contenu de la cellule pour qu’il tienne sur une page, ou augmente la taille de page ou réduis ses marges afin que la hauteur utilisable accueille le contenu.

`BudgetExceededException`

Quand elle est levée. Les primitives de mise en page en mode retenu la lèvent lorsqu’un des quatre paliers de budget de ressources définis dans l’enregistrement de décision d’architecture ADR-020 est franchi et que l’appelant a opté pour un échec dur plutôt que pour le repli souple. Le chemin par défaut ne lève pas : ContainerLayout::acceptChild() renvoie false, l’appelant retombe sur la mise en page en blocs, et un avertissement est émis. L’exception est réservée à la validation au moment de la configuration et aux tests qui affirment le tuple de franchissement exact. Les paliers sont per-child (un flux d’enfant capturé dépasse son plafond), per-container (le budget de nombre de nœuds du Tier 1), per-document (le budget de passe de mise en page ou de profondeur d’imbrication) et global (le plafond de pic de taille de jeu résident à l’échelle du SDK de 256 Mo).
Données portées. Redéfinit getContext(), qui renvoie une forme stable à huit clés consommée par l’outillage de surveillance des performances des applications (APM) : budgetTier, exceededValue, budgetLimit, containerType, phase, breachOrigin, captureSize et processedItemCount. Les quatre premières clés sont le sous-ensemble original de la v1.0.0 et sont toujours peuplées ; les quatre dernières valent par défaut null ou 0 lorsque le constructeur est appelé sans elles. getCausalWarningCode() mappe le tuple (palier, type de conteneur) vers le WarningCode que le chemin de repli souple aurait émis.
Rétablissement. Pour un franchissement de configuration, abaisse la valeur demandée pour la ramener dans l’enveloppe documentée (par exemple, le budget de nœuds retenus accepte 5 000 à 100 000 via Config::withRetainedNodeBudget()). Pour un franchissement de contenu, réduis l’imbrication de conteneurs ou le nombre de nœuds, ou repose-toi sur le repli souple par défaut vers la mise en page en blocs plutôt que d’opter pour la surface d’échec dur.

`UnsupportedNamedPageException`

Quand elle est levée. L’étape paged-media la lève, en mode fermé, lorsqu’un document déclare une règle @page <ident> { … } nommée (liée au contenu via la propriété page: <ident>). Les pages nommées de CSS Paged Media Level 3 §3.4 et Level 4 §3.2 — y compris les pseudo-classes :first, :left, :right et :blank et les surcharges nommées size: et rotate: — sont analysées mais aucun chemin de mise en page de production ne les consomme. Le moteur refuse plutôt que d’émettre la pagination par défaut silencieusement incorrecte que produirait l’abandon de la règle.
Données portées. Redéfinit getContext(), qui renvoie page_names (liste des idents distincts qui ont déclenché l’échec, dans l’ordre de la source), has_size_override (bool), has_rotate_override (bool) et has_pseudo_classes (bool). Les mêmes valeurs sont exposées sur les propriétés publiques pageNames, hasSizeOverride, hasRotateOverride et hasPseudoClasses.
Rétablissement. Supprime les règles @page <ident> nommées et toutes les liaisons page: <ident>, et exprime la géométrie voulue via la règle anonyme prise en charge @page { … } et ses formes à pseudo-classes. Alternativement, épingle une version future qui livre la prise en charge complète de la mise en page de pages nommées.

Typographie et façonnage du texte

`IcuRequirementException`

Quand elle est levée. La segmentation du texte la lève lorsqu’elle a besoin de l’itérateur de saut de ligne des International Components for Unicode (ICU) mais que la politique require-ICU est active (NEXTPDF_REQUIRE_ICU=1) alors que l’extension ext-intl et IntlBreakIterator sont indisponibles.
Données portées. Étend directement RuntimeException, donc elle n’est pas sensible au contexte et n’a pas de getContext(). C’est un raffinement strict de l’exception générique que le même chemin de code levait auparavant, donc les gestionnaires catch (\RuntimeException) existants continuent de fonctionner.
Rétablissement. Installe et active ext-intl afin que l’itérateur de saut ICU soit disponible, ou désactive NEXTPDF_REQUIRE_ICU pour retomber sur le segmenteur non-ICU là où la politique require-ICU n’est pas obligatoire.

`ScriptShaperException`

Quand elle est levée. C’est l’exception de base pour l’interface de fournisseur de service (SPI) de façonnage d’écriture. Elle n’est pas levée directement aujourd’hui ; des sous-types concrets sont levés à la place. Attrape ce type pour traiter tout échec de façonnage en un seul endroit.
Données portées. Étend directement RuntimeException ; non sensible au contexte, pas de getContext().
Rétablissement. Branche sur le sous-type concret. Voir NotYetImplementedException ci-dessous pour le seul sous-type livré dans la version actuelle.

`NotYetImplementedException`

Quand elle est levée. Chaque façonneur d’écriture de remplacement la lève depuis le corps de son shape() pour les écritures dont le façonnage concret est différé (le mongol et le tibétain). La couture SPI de façonnage est prête sur le plan architectural, mais le façonnage réel est en attente d’une fixture validée par un locuteur natif. Lever une exception plutôt qu’un no-op silencieux fait remonter un câblage de production accidentel à l’exécution plutôt que d’émettre du texte non façonné dans un PDF qui revendique une accessibilité balisée.
Données portées. Étend ScriptShaperException (et donc RuntimeException), donc elle n’est pas sensible au contexte et n’a pas de getContext(). Les données de diagnostic sont sur ses propriétés public readonly : bcp47LanguageTag (l’étiquette BCP-47 du run, telle que mn-Mong ou bo-Tibt) et missingCapability (la capacité concrète qui manque à l’implémentation). Le message inclut les deux.
Rétablissement. Ne route pas les runs dans les écritures non implémentées à travers le façonneur en production. Détecte l’étiquette de langue en amont et soit retombe sur un chemin de rendu différent, soit épingle une version future qui livre le façonnage pour l’écriture concernée.

Profils de sortie du writer et chiffrement

`Pdf14FeatureRejectedException`

Quand elle est levée. Le writer la lève lorsqu’un document contient une fonctionnalité interdite sous le profil de sortie PDF 1.4 (ISO 19005-1:2005 / PDF/A-1), qui prohibe les constructions introduites dans des versions PDF ultérieures.
Données portées. Étend NextPdfException mais ne redéfinit pas getContext(), donc getContext() renvoie un tableau vide. Les données de diagnostic sont sur ses propriétés public readonly : feature (le nom de la fonctionnalité rejetée), reason (pourquoi elle est interdite) et isoClause (la référence de clause ISO). Le message combine les trois.
Rétablissement. Supprime ou remplace la fonctionnalité rejetée par un équivalent compatible PDF 1.4, ou cible un profil de sortie supérieur qui permet la fonctionnalité.

`Pdf20FeatureRejectedException`

Quand elle est levée. Le writer la lève lorsqu’un document contient une fonctionnalité interdite sous le profil de sortie PDF 2.0 strict. ISO 32000-2:2020 déprécie des constructions que PDF 1.7 permettait encore — notamment les polices Standard 14 Type 1 (§9.6.2), qui doivent être embarquées dans un document PDF 2.0 conforme.
Données portées. Même forme que Pdf14FeatureRejectedException : étend NextPdfException, ne redéfinit pas getContext() (renvoie un tableau vide), et expose feature, reason et isoClause en tant que propriétés public readonly.
Rétablissement. Remédie à la fonctionnalité rejetée — par exemple, embarque les polices base 14 — ou prends l’échappatoire documentée là où il en existe une (pour les polices base 14 non embarquées, Document::allowNonEmbeddedBase14()).

`PublicKeyEncryptionUnsupportedException`

Quand elle est levée. PdfWriter::build() la lève au point d’entrée lorsque l’encryptionMode du document est pubkey (une liste de destinataires à clé publique) avant que la répartition du chiffrement du corps de flux à clé publique côté writer ne soit câblée. Refuser d’emblée empêche d’émettre silencieusement un PDF non chiffré que l’appelant croyait chiffré.
Données portées. Étend directement RuntimeException, donc elle n’est pas sensible au contexte et n’a pas de getContext(). C’est un raffinement strict de l’exception générique que le même site levait auparavant, donc les gestionnaires catch (\RuntimeException) existants continuent de fonctionner.
Rétablissement. Utilise un mode de chiffrement pris en charge (chiffrement par mot de passe) au lieu de la liste de destinataires à clé publique, ou épingle une version qui livre la prise en charge du chiffrement à clé publique. Ne traite pas la sortie comme chiffrée lorsque ceci est levé.

Entrée du reader et des métadonnées

`UnsupportedPdfStructureException`

Quand elle est levée. Le lecteur de graphe d’objets la lève, en mode fermé, lorsqu’un PDF d’entrée tombe en dehors de son enveloppe prise en charge. Le lecteur prend en charge les tables de référence croisée classiques (ISO 32000-2:2020 §7.5.4), les flux de référence croisée (§7.5.8), les objets compressés en flux d’objets (§7.5.7), les chaînes /Prev multi-révisions (§7.5.6) et les fichiers à référence hybride via /XRefStm (§7.5.8.4). Tout ce qui est en dehors de cette enveloppe fait remonter cette exception plutôt qu’une analyse partielle ou devinée. Les constructeurs nommés correspondent aux cas de raison : encrypted(), damagedCrossReference(), cyclicReferenceChain(), nonConformantObjectStream(), irresolvableObjectCollision(), truncatedFile() et crossReferenceOffsetOutOfBounds().
Données portées. Étend directement RuntimeException, donc elle n’est pas sensible au contexte et n’a pas de getContext(). Elle expose une propriété public readonly reason de type UnsupportedPdfStructureReason (une énumération) afin que les appelants branchent sur la catégorie précise sans analyser le message ; une chaîne detail optionnelle et un throwable previous peuvent ajouter un contexte borné et non sensible. Le message par défaut est le résumé non divulgant de la raison.
Rétablissement. Branche sur reason. Pour EncryptedDocument, exécute une étape de déchiffrement avant la lecture, puisque le déchiffrement est en dehors de la portée du lecteur. Pour DamagedCrossReference, TruncatedFile ou CrossReferenceOffsetOutOfBounds, traite le fichier comme malformé ou incomplet et ré-acquiers ou répare la source. Pour CyclicReferenceChain, NonConformantObjectStream ou IrresolvableObjectCollision, l’entrée viole le modèle structurel et ne peut pas être lue telle quelle.

`PacketTooLargeException`

Quand elle est levée. Le lecteur de métadonnées XMP en flux la lève lorsqu’un paquet XMP embarqué dépasse le plafond d’octets configuré. C’est une garde défensive contre les entrées de type expansion d’entité et explosion quadratique (un plafond de pic de 128 Mo contre du XMP embarqué à l’échelle du gigaoctet).
Données portées. Étend NextPdfException mais ne redéfinit pas getContext(), donc getContext() renvoie un tableau vide. Les données de diagnostic sont sur ses propriétés public readonly : byteCount (le nombre d’octets observé) et cap (le plafond configuré en octets). Le message rapporte les deux.
Rétablissement. Rejette ou saute les métadonnées surdimensionnées comme malveillantes ou malformées. Si un document légitime a réellement besoin d’un paquet plus grand, relève délibérément le plafond configuré, en pesant le risque d’épuisement de mémoire que la garde existe pour prévenir.

Voir aussi

Index de la référence des erreurs
Dépannage des polices et du balisage — pour les symptômes de NotYetImplementedException, ScriptShaperException et IcuRequirementException.
Dépannage de la validation PDF/A et PDF/UA — pour les symptômes de Pdf14FeatureRejectedException et Pdf20FeatureRejectedException.
Dépannage du chiffrement et des permissions — pour PublicKeyEncryptionUnsupportedException et la raison EncryptedDocument du lecteur.