Errori di rendering e I/O

Ambito

Queste voci coprono le eccezioni di rendering e input/output (I/O) sollevate mentre la pipeline HTML dispone il contenuto nel layout, il resolver dei paged media assegna la geometria di pagina, lo shaper del testo elabora gli script complessi, la fase di tipografia interrompe le righe, il writer serializza un documento, il reader analizza un PDF esistente e la fase dei metadati legge un pacchetto Extensible Metadata Platform (XMP).

Due gerarchie di base compaiono di seguito, e la differenza determina quali dati diagnostici si possono leggere dopo un catch:

• NextPdfException implementa ContextAwareExceptionInterface::getContext(): array. L’implementazione di base restituisce un array vuoto; una sottoclasse trasporta chiavi strutturate solo quando sovrascrive getContext(). Le sottoclassi che non la sovrascrivono espongono comunque i propri dati tramite proprietà public readonly.
• Diverse classi qui estendono direttamente la RuntimeException di PHP. Non sono context-aware e non hanno un metodo getContext(); leggere invece il loro getMessage() e qualsiasi proprietà pubblica.

Ogni voce indica la classe esatta, la condizione di trigger, le chiavi di contesto o le proprietà pubbliche che trasporta e il percorso di recupero.

Layout HTML e paged media

UnsplittableContentException

• Quando viene sollevata. Il motore di layout HTML la solleva quando il contenuto contrassegnato break-inside: avoid (una cella di tabella il cui vincolo di interruzione è Avoid) ha un’altezza misurata che supera l’altezza utilizzabile di una singola pagina. Il motore non può soddisfare contemporaneamente il vincolo avoid-break e il confine di pagina, perciò fallisce anziché provocare silenziosamente un overflow.
• Dati trasportati. Estende NextPdfException ma non sovrascrive getContext(), quindi getContext() restituisce un array vuoto. I dati diagnostici sono su proprietà public readonly: gridRow (int), gridCol (int), contentHeight (float, punti) e pageHeight (float, punti). Il messaggio indica le coordinate della cella ed entrambe le altezze.
• Recupero. Rimuovere il vincolo break-inside: avoid sulla cella problematica, ridurre il contenuto della cella affinché stia in una pagina, oppure aumentare la dimensione di pagina o ridurne i margini così che l’altezza utilizzabile accolga il contenuto.

BudgetExceededException

• Quando viene sollevata. Le primitive di layout in modalità retained la sollevano quando uno dei quattro tier di budget delle risorse definiti nella architecture decision record ADR-020 viene violato e il chiamante ha optato per un guasto rigido anziché per il fallback morbido. Il percorso predefinito non solleva eccezioni: ContainerLayout::acceptChild() restituisce false, il chiamante ripiega sul layout a blocchi e viene emesso un avviso. L’eccezione è riservata alla convalida al momento della configurazione e ai test che asseriscono la tupla esatta di violazione. I tier sono per-child (uno stream di figlio catturato supera il proprio limite), per-container (il budget di conteggio dei nodi di Tier 1), per-document (il budget di passaggi di layout o profondità di annidamento) e global (il tetto a livello di SDK di 256 MB di picco di resident set size).
• Dati trasportati. Sovrascrive getContext(), che restituisce una forma stabile a otto chiavi consumata dalla strumentazione di application performance monitoring (APM): budgetTier, exceededValue, budgetLimit, containerType, phase, breachOrigin, captureSize e processedItemCount. Le prime quattro chiavi sono il sottoinsieme originale v1.0.0 e sono sempre popolate; le ultime quattro hanno valore predefinito null o 0 quando il costruttore viene chiamato senza di esse. getCausalWarningCode() mappa la tupla (tier, container-type) sul WarningCode che il percorso di fallback morbido avrebbe emesso.
• Recupero. Per una violazione di configurazione, riportare il valore richiesto entro l’envelope documentato (ad esempio, il budget dei nodi retained accetta da 5.000 a 100.000 tramite Config::withRetainedNodeBudget()). Per una violazione di contenuto, ridurre l’annidamento dei container o il conteggio dei nodi, oppure affidarsi al fallback morbido predefinito al layout a blocchi anziché optare per la superficie a guasto rigido.

UnsupportedNamedPageException

• Quando viene sollevata. La fase dei paged media la solleva, fail-closed, quando un documento dichiara una regola @page <ident> { … } denominata (vincolata al contenuto tramite la proprietà page: <ident>). Le pagine denominate di CSS Paged Media Level 3 §3.4 e Level 4 §3.2 — incluse le pseudo-classi :first, :left, :right e :blank e gli override denominati size: e rotate: — vengono analizzate ma nessun percorso di layout di produzione le consuma. Il motore rifiuta anziché emettere la paginazione predefinita silenziosamente errata che scartare la regola produrrebbe.
• Dati trasportati. Sovrascrive getContext(), che restituisce page_names (elenco degli ident distinti che hanno innescato il guasto, in ordine di sorgente), has_size_override (bool), has_rotate_override (bool) e has_pseudo_classes (bool). Gli stessi valori sono esposti sulle proprietà pubbliche pageNames, hasSizeOverride, hasRotateOverride e hasPseudoClasses.
• Recupero. Rimuovere le regole @page <ident> denominate e qualsiasi binding page: <ident>, ed esprimere la geometria desiderata tramite la regola @page { … } non denominata supportata e le sue forme con pseudo-classe. In alternativa, agganciarsi a una release futura che introduce il pieno supporto al layout delle pagine denominate.

Tipografia e shaping del testo

IcuRequirementException

• Quando viene sollevata. La segmentazione del testo la solleva quando necessita dell’iteratore di interruzione di riga di International Components for Unicode (ICU) ma la policy require-ICU è attiva (NEXTPDF_REQUIRE_ICU=1) mentre l’estensione ext-intl e IntlBreakIterator non sono disponibili.
• Dati trasportati. Estende direttamente RuntimeException, perciò non è context-aware e non ha getContext(). È un raffinamento strict dell’eccezione generica che lo stesso percorso di codice sollevava in precedenza, perciò i gestori catch (\RuntimeException) esistenti continuano a funzionare.
• Recupero. Installare e abilitare ext-intl così che l’iteratore di interruzione ICU sia disponibile, oppure rimuovere NEXTPDF_REQUIRE_ICU per ripiegare sul segmentatore non-ICU dove la policy require-ICU non è obbligatoria.

ScriptShaperException

• Quando viene sollevata. È l’eccezione base per la service provider interface (SPI) di shaping degli script. Oggi non viene sollevata direttamente; vengono sollevati invece i sottotipi concreti. Intercettare questo tipo per gestire in un unico punto qualsiasi guasto di shaping.
• Dati trasportati. Estende direttamente RuntimeException; non context-aware, nessun getContext().
• Recupero. Diramare sul sottotipo concreto. Vedere NotYetImplementedException di seguito per l’unico sottotipo fornito nella release corrente.

NotYetImplementedException

• Quando viene sollevata. Ogni script-shaper segnaposto la solleva dal proprio corpo shape() per gli script il cui shaping concreto è differito (mongolo e tibetano). Il seam della SPI di shaping è pronto a livello di architettura, ma lo shaping reale è in attesa di una fixture validata da madrelingua. Sollevare un’eccezione anziché un no-op silenzioso fa emergere a runtime un collegamento di produzione accidentale, invece di emettere testo non sottoposto a shaping in un PDF che dichiara accessibilità con tag.
• Dati trasportati. Estende ScriptShaperException (e quindi RuntimeException), perciò non è context-aware e non ha getContext(). I dati diagnostici sono sulle sue proprietà public readonly: bcp47LanguageTag (il tag BCP-47 del run, come mn-Mong o bo-Tibt) e missingCapability (la capacità concreta che manca all’implementazione). Il messaggio include entrambi.
• Recupero. Non instradare in produzione i run negli script non implementati attraverso lo shaper. Rilevare il tag di lingua a monte e ripiegare su un percorso di rendering diverso oppure agganciarsi a una release futura che introduce lo shaping per lo script interessato.

Profili di output del writer e cifratura

Pdf14FeatureRejectedException

• Quando viene sollevata. Il writer la solleva quando un documento contiene una funzionalità vietata sotto il profilo di output PDF 1.4 (ISO 19005-1:2005 / PDF/A-1), che proibisce i costrutti introdotti in versioni PDF successive.
• Dati trasportati. Estende NextPdfException ma non sovrascrive getContext(), quindi getContext() restituisce un array vuoto. I dati diagnostici sono sulle sue proprietà public readonly: feature (il nome della funzionalità rifiutata), reason (perché è vietata) e isoClause (il riferimento alla clausola ISO). Il messaggio combina tutti e tre.
• Recupero. Rimuovere o sostituire la funzionalità rifiutata con un equivalente compatibile con PDF 1.4, oppure puntare a un profilo di output superiore che la consente.

Pdf20FeatureRejectedException

• Quando viene sollevata. Il writer la solleva quando un documento contiene una funzionalità vietata sotto il profilo di output PDF 2.0 strict. ISO 32000-2:2020 depreca costrutti che PDF 1.7 ancora consentiva — in particolare i font Type 1 Standard 14 (§9.6.2), che devono essere incorporati in un documento PDF 2.0 conforme.
• Dati trasportati. Stessa forma di Pdf14FeatureRejectedException: estende NextPdfException, non sovrascrive getContext() (restituisce un array vuoto) ed espone feature, reason e isoClause come proprietà public readonly.
• Recupero. Rimediare alla funzionalità rifiutata — ad esempio, incorporare i font base 14 — oppure usare la via di uscita documentata dove esiste (per i font base 14 non incorporati, Document::allowNonEmbeddedBase14()).

PublicKeyEncryptionUnsupportedException

• Quando viene sollevata. PdfWriter::build() la solleva al punto di ingresso quando l’encryptionMode del documento è pubkey (un elenco di destinatari a chiave pubblica) prima che il dispatch lato writer di cifratura del corpo dello stream a chiave pubblica sia collegato. Rifiutare in anticipo impedisce di emettere silenziosamente un PDF non cifrato che il chiamante credeva cifrato.
• Dati trasportati. Estende direttamente RuntimeException, perciò non è context-aware e non ha getContext(). È un raffinamento strict dell’eccezione generica che lo stesso sito sollevava in precedenza, perciò i gestori catch (\RuntimeException) esistenti continuano a funzionare.
• Recupero. Usare una modalità di cifratura supportata (cifratura basata su password) anziché l’elenco di destinatari a chiave pubblica, oppure agganciarsi a una release che introduce il supporto alla cifratura a chiave pubblica. Non considerare l’output come cifrato quando questa viene sollevata.

Input del reader e dei metadati

UnsupportedPdfStructureException

• Quando viene sollevata. Il reader del grafo di oggetti la solleva, fail-closed, quando un PDF di input ricade fuori dal suo envelope supportato. Il reader supporta le tabelle di cross-reference classiche (ISO 32000-2:2020 §7.5.4), gli stream di cross-reference (§7.5.8), gli oggetti compressi in object stream (§7.5.7), le catene /Prev multi-revisione (§7.5.6) e i file a riferimento ibrido tramite /XRefStm (§7.5.8.4). Qualsiasi cosa fuori da quel envelope fa emergere questa eccezione anziché un parsing parziale o indovinato. I costruttori denominati mappano ai casi di motivo: encrypted(), damagedCrossReference(), cyclicReferenceChain(), nonConformantObjectStream(), irresolvableObjectCollision(), truncatedFile() e crossReferenceOffsetOutOfBounds().
• Dati trasportati. Estende direttamente RuntimeException, perciò non è context-aware e non ha getContext(). Espone una proprietà public readonly reason di tipo UnsupportedPdfStructureReason (un enum), così che i chiamanti diramino sulla categoria precisa senza analizzare il messaggio; una stringa detail opzionale e un throwable previous possono aggiungere contesto limitato e non sensibile. Il messaggio predefinito è il riepilogo non-leaking del motivo.
• Recupero. Diramare su reason. Per EncryptedDocument, eseguire un passaggio di decifratura prima della lettura, poiché la decifratura è fuori dall’ambito del reader. Per DamagedCrossReference, TruncatedFile o CrossReferenceOffsetOutOfBounds, considerare il file come malformato o incompleto e riacquisire o riparare l’origine. Per CyclicReferenceChain, NonConformantObjectStream o IrresolvableObjectCollision, l’input viola il modello strutturale e non può essere letto così com’è.

PacketTooLargeException

• Quando viene sollevata. Il reader dei metadati XMP in streaming la solleva quando un pacchetto XMP incorporato supera il tetto di byte configurato. È una guardia difensiva contro input in stile entity-expansion e quadratic-blowup (un tetto di picco di 128 MB contro XMP incorporato su scala di gigabyte).
• Dati trasportati. Estende NextPdfException ma non sovrascrive getContext(), quindi getContext() restituisce un array vuoto. I dati diagnostici sono sulle sue proprietà public readonly: byteCount (il conteggio di byte osservato) e cap (il limite configurato in byte). Il messaggio riporta entrambi.
• Recupero. Rifiutare o saltare i metadati sovradimensionati come malevoli o malformati. Se un documento legittimo necessita davvero di un pacchetto più grande, innalzare deliberatamente il limite configurato, valutando il rischio di esaurimento della memoria che la guardia esiste per prevenire.

Vedere anche

• Indice del riferimento degli errori
• Risoluzione dei problemi di font e tagging — per i sintomi di NotYetImplementedException, ScriptShaperException e IcuRequirementException.
• Risoluzione dei problemi di convalida PDF/A e PDF/UA — per i sintomi di Pdf14FeatureRejectedException e Pdf20FeatureRejectedException.
• Risoluzione dei problemi di cifratura e permessi — per PublicKeyEncryptionUnsupportedException e il motivo EncryptedDocument del reader.