Errori core e generali

Ambito

Queste voci coprono le eccezioni core e di uso generale sollevate da NextPDF. La maggior parte estende la base NextPdfException, che a sua volta estende \RuntimeException e implementa ContextAwareExceptionInterface. Tale interfaccia espone un unico metodo, getContext(): array, che restituisce una mappa piatta in snake_case di primitivi sicuri da serializzare in un log o in un payload APM.

Intercettare la famiglia NextPdfException con un singolo catch (NextPdfException $e). Aggiungere anche un catch (\RuntimeException $e) per coprire i pochi errori di basso livello di questo insieme che estendono direttamente \RuntimeException (elencati di seguito). La base NextPdfException::getContext() restituisce un array vuoto; le sottoclassi la sovrascrivono per aggiungere campi di dominio. Dove una classe non sovrascrive getContext(), eredita l’array vuoto e il dettaglio diagnostico risiede invece nel messaggio e nei getter tipizzati.

Quattro tipi di questo insieme non estendono NextPdfException: BlackPointCompensationUnsupportedException e UnsupportedSourceDocumentException estendono direttamente \RuntimeException (intercettarle come \RuntimeException), mentre ComplianceViolation e RuleViolation sono value object, non eccezioni — sono documentate qui perché modellano i dati di errore e di violazione restituiti dal motore.

Eccezione base

NextPdfException

• Che cos’è. Base abstract per ogni eccezione sollevata da NextPDF core e dai suoi pacchetti di estensione. Estende \RuntimeException e implementa ContextAwareExceptionInterface. Intercettare questo unico tipo cattura qualsiasi errore della libreria.
• Contesto. La getContext() di base restituisce un array vuoto. Le sottoclassi la sovrascrivono per restituire campi specifici del dominio.
• Recupero. Non viene sollevata direttamente. Usarla come tipo catch-all; diramare sulla sottoclasse concreta per una gestione specifica.

Configurazione e gating delle funzionalità

InvalidConfigException

• Quando viene sollevata. Quando un valore Config o una combinazione di valori non è valida — un’impostazione obbligatoria mancante, un’opzione mutuamente esclusiva o un valore fuori dall’intervallo accettato. Segnala un errore dello sviluppatore: il codice chiamante ha fornito una configurazione che deve essere corretta prima di riprovare. Il messaggio riporta la chiave, il tipo o l’intervallo attesi e il tipo di debug effettivo del valore fornito.
• Contesto. getContext() restituisce config_key, given_value ed expected_type. Getter tipizzati: getConfigKey(), getGivenValue(), getExpectedType().
• Recupero. Azione dello sviluppatore: correggere la chiave di configurazione indicata portandola a un valore del tipo o dell’intervallo atteso prima di richiamare di nuovo NextPDF.

NotImplementedException

• Quando viene sollevata. Quando si raggiunge un punto di ingresso pubblico dell’API la cui implementazione è intenzionalmente assente nella release corrente. Usata per gli shim deprecati che esistono per offrire ai chiamanti pre-bisect un errore rumoroso e azionabile anziché un no-op silenzioso. Il messaggio combina un’etichetta feature ricercabile a macchina e un riferimento followUp (ID del difetto, ancora di tracciamento o nome dello sprint).
• Contesto. Non sovrascrive getContext(), quindi restituisce un array vuoto. I valori $feature e $followUp sono proprietà pubbliche readonly e sono incorporati nel messaggio.
• Recupero. Azione del chiamante della libreria: rimuovere la chiamata, oppure agganciarsi a una release futura che introduce il follow-up indicato.

IncompatibleFeatureFlagsException

• Quando viene sollevata. Al momento della build di Config (Config::validate()) quando una combinazione di CssFeatureFlags è internamente incoerente — un flag presuppone un altro flag che è disabilitato. L’unica combinazione vietata oggi è layoutSubgrid = true con layoutGrid = false: un asse con subgrid deriva le proprie linee di griglia da un contenitore di griglia padre (CSS Grid Layout Module Level 2 §1), quindi subgrid senza grid descrive una griglia che non può esistere. Il controllo viene eseguito sui flag risolti, perciò CssRenderingMode::Safe (che forza la disattivazione di ogni funzionalità da Phase 4 in poi) maschera la combinazione anziché farla scattare. Estende StrictModeViolation.
• Contesto. getContext() unisce i campi di modalità strict del genitore (cssDeviation, excId, chunkSha256, location) con i booleani layoutGrid e layoutSubgrid. La location è Config::validate() e cssDeviation codifica la coppia di flag.
• Recupero. Azione del chiamante della libreria: abilitare layoutGrid insieme a layoutSubgrid, oppure disabilitare layoutSubgrid.

IncompatibleRenderingModeException

• Quando viene sollevata. Al momento della build di Config quando un abbinamento CssRenderingMode e CssLayoutMode ricade fuori dalle celle compatibili della matrice delle modalità. L’unico abbinamento vietato oggi è CssRenderingMode::Safe + CssLayoutMode::Retained — Safe forza la disattivazione di ogni funzionalità da Phase 4 in poi, lasciando i contesti di formattazione in modalità retained (Grid, Subgrid, @container) senza consumatori, perciò la combinazione viene rifiutata anziché lasciata degradare silenziosamente. Estende StrictModeViolation.
• Contesto. getContext() unisce i campi di modalità strict del genitore con mode1 (il valore della modalità di rendering) e mode2 (il valore della modalità di layout). Il cssDeviation codifica la coppia di modalità; location è Config::validate().
• Recupero. Azione del chiamante della libreria: scegliere Safe + Streaming per il rollback, oppure una modalità di rendering non-Safe (Normal / Strict / Audit) con Retained per Grid / Subgrid / Container Queries.

StrictModeViolation

• Quando viene sollevata. Base abstract per qualsiasi eccezione di deviazione dalla specifica sollevata sotto CssRenderingMode::Strict. In modalità strict, qualsiasi deviazione CSS rilevata non collegata a una voce di eccezione EXC-NNN registrata solleva un’istanza di questa classe (o di una sottoclasse) nel punto di rilevamento. Non viene sollevata direttamente; vedere IncompatibleFeatureFlagsException e IncompatibleRenderingModeException.
• Contesto. getContext() restituisce i quattro campi di ADR-023: cssDeviation (etichetta breve per il costrutto in deviazione), excId (identificatore di registro quando registrato, altrimenti null), chunkSha256 (hash del chunk di citazione della specifica quando noto, altrimenti null) e location (origine leggibile dal chiamante, altrimenti null).
• Recupero. Azione del chiamante della libreria: registrare la deviazione come una nuova voce EXC-NNN approvata, oppure correggere il renderer per rimuovere la deviazione.

Input HTML e CSS

HtmlParsingException

• Quando viene sollevata. Quando il parsing dell’input HTML o la costruzione del DOM falliscono: dichiarazioni di charset non valide, violazioni del limite di dimensione dell’input, profondità di annidamento eccessiva, overflow del conteggio degli elementi ed errori nella struttura delle tabelle, come un numero massimo di righe. L’esaurimento di risorse specifico del CSS è segnalato invece da CssParserLimitExceededException e CssResolutionBudgetExceededException.
• Contesto. getContext() restituisce html_snippet (un breve estratto troncato dell’HTML problematico), position (offset in byte, oppure -1 se sconosciuto) e rule (il vincolo del parser violato). Getter tipizzati: getHtmlSnippet(), getPosition(), getRule().
• Recupero. Azione dello sviluppatore: semplificare l’input HTML o regolare i limiti del parser.

CssParserLimitExceededException

• Quando viene sollevata. Quando l’input CSS supera un limite di sicurezza configurato del parser. Due categorie sono coperte tramite i costruttori denominati: forByteLimit() (foglio di stile troppo grande per un’elaborazione regex sicura) e forNestingDepth() (ricorsione di annidamento CSS troppo profonda). Entrambi i messaggi indicano il valore effettivo e il limite.
• Contesto. getContext() restituisce limit_type (byte o nesting_depth), actual e limit.
• Recupero. Azione dello sviluppatore: suddividere il foglio di stile in fogli più piccoli, oppure ridurre la profondità di annidamento, oppure innalzare il limite configurato.

CssResolutionBudgetExceededException

• Quando viene sollevata. Quando la risoluzione CSS :has() supera il proprio budget di attraversamento. Il resolver :has() a due passaggi impone un budget rigoroso di visite ai nodi per impedire che selettori patologici causino percorsi quadratici nel documento; una volta che il conteggio totale delle visite supera il limite, il foglio di stile viene rifiutato perché troppo complesso. Il messaggio indica il conteggio delle visite e il budget.
• Contesto. getContext() restituisce visits e budget. Getter tipizzati: getVisits(), getBudget().
• Recupero. Azione dello sviluppatore: ridurre la complessità dei selettori, oppure innalzare il budget configurato.

Font e immagini

FontNotFoundException

• Quando viene sollevata. Quando un file di font non può essere individuato o letto a livello di file system: la famiglia o il percorso richiesti non esistono, non sono leggibili, oppure la directory dei font configurata è inaccessibile. I dati del font possono essere validi — questo segnala soltanto che non sono raggiungibili. Il messaggio elenca i percorsi consultati.
• Contesto. getContext() restituisce font_name, search_paths (un elenco) e fallback_attempted (un bool). Getter tipizzati: getFontName(), getSearchPaths(), wasFallbackAttempted().
• Recupero. Azione dello sviluppatore: verificare il percorso del font. Azione dell’infrastruttura: correggere i permessi del file sul file o sulla directory dei font.

FontParsingException

• Quando viene sollevata. Quando un file di font viene trovato ma il suo contenuto non è utilizzabile: è corrotto, in un formato non supportato o privo delle tabelle obbligatorie. Copre i guasti di convalida strutturale durante il parsing di TrueType, Type 1, CFF e OpenType — header troncati, directory delle tabelle non valide, tabelle obbligatorie mancanti (head, hhea, OS/2), errori di unpacking e violazioni di dimensione. Il messaggio indica il file e l’errore di parsing.
• Contesto. getContext() restituisce font_file e parse_error. Getter tipizzati: getFontFile(), getParseError().
• Recupero. Azione dello sviluppatore: sostituire il file di font con uno valido.

ImageProcessingException

• Quando viene sollevata. Quando un’immagine non può essere decodificata, è in un formato non supportato o fallisce l’elaborazione GD/Imagick: magic byte non riconoscibili, dati JPEG corrotti, tipi MIME non supportati, violazioni del limite di dimensione del file e guasti di allocazione delle risorse GD. L’immagine era accessibile ma i suoi dati di pixel non hanno potuto essere estratti per l’incorporamento.
• Contesto. getContext() restituisce image_path (vuoto per i dati inline), format (rilevato o atteso, ad esempio jpeg, png, unknown) e operation (ad esempio decode, resize, embed). Getter tipizzati: getImagePath(), getFormat(), getOperation().
• Recupero. Azione dello sviluppatore: fornire un file di immagine valido e supportato.

Output, layout e serializzazione

CompressionException

• Quando viene sollevata. Quando la compressione o la decompressione FlateDecode (zlib) fallisce — guasti di gzcompress/gzuncompress su content stream, dati dei font, contenuto delle pagine, dati degli allegati e stream di cross-reference. In genere uno stream di input corrotto, memoria insufficiente o un’estensione zlib mancante.
• Contesto. getContext() restituisce algorithm (nome del filtro, ad esempio FlateDecode, LZWDecode) e stream_length (lunghezza in byte, oppure -1 se sconosciuta). Getter tipizzati: getAlgorithm(), getStreamLength().
• Recupero. Azione dell’infrastruttura: verificare che ext-zlib sia caricata e che la memoria sia sufficiente.

WriterException

• Quando viene sollevata. Quando la serializzazione PDF, la linearizzazione o l’output I/O falliscono: errori di scrittura dello stream di PdfWriter, corruzione della tabella di cross-reference, guasti nella generazione di header/trailer, guasti nella risoluzione dei riferimenti agli oggetti, errori di scrittura su file e overflow del buffer di output. Un documento valido in memoria non ha potuto essere serializzato in un flusso di byte valido. Il messaggio indica la fase.
• Contesto. getContext() restituisce output_path (vuoto per l’output su stringa) e writer_state (la fase, ad esempio header, body, xref, trailer). Getter tipizzati: getOutputPath(), getWriterState().
• Recupero. Azione dell’infrastruttura: verificare lo spazio su disco, i permessi del file e lo stream di output.

PageLayoutException

• Quando viene sollevata. Quando i vincoli di layout di pagina non possono essere soddisfatti: violazioni del layout a colonne (larghezza insufficiente, numero di colonne non valido), overflow del contenuto oltre i confini della pagina e conflitti di margine. Il layout richiesto è geometricamente impossibile per le dimensioni di pagina e il contenuto dati. Il messaggio indica il numero di pagina quando noto e il vincolo violato.
• Contesto. getContext() restituisce page_number (a base uno, oppure 0 se sconosciuto) e constraint. Getter tipizzati: getPageNumber(), getConstraint().
• Recupero. Azione dello sviluppatore: regolare la dimensione di pagina, i margini, le impostazioni delle colonne o il contenuto.

TemplateException

• Quando viene sollevata. Quando un’operazione di import o riuso di un template PDF fallisce in TemplateManager: transizioni di stato del template non valide (avvio o chiusura di template fuori sequenza), riferimento a un template inesistente e guasti di compressione dello stream durante la serializzazione del template. Il messaggio indica l’operazione e l’id del template quando assegnato.
• Contesto. getContext() restituisce template_id (vuoto se non ancora assegnato) e operation (ad esempio begin, end, use, serialize). Getter tipizzati: getTemplateId(), getOperation().
• Recupero. Azione dello sviluppatore: correggere la sequenza d’uso del template o il PDF di origine.

Invarianti dei content stream

ContentStreamBalanceException

• Quando viene sollevata. Quando un ContentStreamBuilder rileva una coppia di operatori sbilanciata alla chiusura dello stream (o a metà stream quando le invarianti vengono asserite con verifica anticipata). Cattura i contatori di profondità che hanno fallito l’invariante di bilanciamento, così che il logging possa identificare quale emitter abbia lasciato aperto un q, BT o BMC senza il corrispondente Q, ET o EMC. Secondo ISO 32000-2:2020 §8.4.2 (graphics-state stack), §9.4.1 (text objects) e §14.6 (marked content).
• Contesto. getContext() restituisce graphics_depth, text_block_depth, marked_content_depth e offending_operator. Getter tipizzati: getGraphicsDepth(), getTextBlockDepth(), getMarkedContentDepth(), getOffendingOperator().
• Recupero. Azione dello sviluppatore: individuare l’emitter che ha aperto un costrutto senza chiuderlo.

GraphicsStateBalanceException

• Quando viene sollevata. Quando un content stream PDF si chiude con operatori q/Q sbilanciati. ISO 32000-2:2020 §8.4.2 richiede che ogni salvataggio dello stato grafico (q) sia bilanciato esattamente da un ripristino (Q) prima che lo stream termini; lo sbilanciamento fa propagare trasformazioni, percorsi di clipping, colori e rendering intent nelle pagine successive o nei Form XObject. Sollevata solo quando il controllo strict dello stato grafico è abilitato (NEXTPDF_GFXSTATE_STRICT=1); in modalità relaxed viene invece emesso un avviso tramite trigger_error().
• Contesto. getContext() restituisce save_depth (positivo per troppi salvataggi, negativo per troppi ripristini). Getter tipizzato: getSaveDepth().
• Recupero. Azione dello sviluppatore: individuare la coppia save()/restore() non corrispondente.

MissingShadingResourceException

• Quando viene sollevata. Quando ConicGradientRenderer::render() viene invocato senza un contesto di registro delle risorse di Shading. La breaking change v10.0.0 ha rimosso il precedente percorso surrogato a marker map implicita: i chiamanti devono costruire il renderer con un ShadingResourceRegistryInterface affinché l’oggetto indiretto /ShadingType 4 sia registrato nel sottodizionario delle risorse di Shading della pagina (ISO 32000-2 §8.7.4.2 / §8.7.4.3). Il messaggio indica il contesto del chiamante e rimanda alla nota di migrazione v9.x→v10.0.
• Contesto. getContext() restituisce context (una breve etichetta di contesto del chiamante, ad esempio ConicGradientRenderer::render).
• Recupero. Azione del chiamante della libreria: collegare un’istanza di registro delle risorse di Shading nel costruttore del renderer prima di chiamare render().

Linearizzazione (Fast Web View)

LinearizationInvariantException

• Quando viene sollevata. Quando il Linearizer v2 a tre passaggi rileva che le sue asserzioni MEASURE → PLACE → FILL sono state violate: un conteggio di byte del Pass 3 che non corrisponde alla lunghezza di file prevista dal Pass 1 (deriva dell’offset), un segnaposto del dizionario di linearizzazione troppo piccolo per la larghezza serializzata, oppure un offset dell’hint stream /H [offset length] che non corrisponde all’output finale. Far emergere questo anziché emettere un PDF danneggiato è una garanzia di sicurezza dichiarata.
• Contesto. getContext() restituisce invariant (il nome dell’invariante violata), expected, actual e delta (la differenza con segno). Getter tipizzati: getInvariant(), getExpectedValue(), getActualValue().
• Recupero. Azione del manutentore: aprire una segnalazione di bug — queste invarianti dovrebbero valere per tutti gli input ben formati. Acquisire l’eccezione precedente concatenata.

LinearizationUnimplementedException

• Quando viene sollevata. Quando il feature flag del linearizer è impostato su un backend intenzionalmente disabilitato. Attualmente sollevata solo per linearizerVersion === 'v1-noop', l’impostazione di downgrade d’emergenza che rifiuta tutti i tentativi di linearizzazione a runtime senza una modifica al codice o un redeploy — utile per disattivare con kill-switch Fast Web View in produzione.
• Contesto. getContext() restituisce reason (una breve spiegazione leggibile). Getter tipizzato: getReason().
• Recupero. Azione dell’operatore / release engineering: regolare la configurazione o aggiornare a una versione corretta del backend.

Invarianti di conformità e profilo

ConformanceViolationException

• Quando viene sollevata. Quando una funzionalità richiesta non può essere emessa senza violare il contratto di conformità ISO dichiarato del documento, e il motore adotta il fail-closed anziché scrivere un oggetto non conforme. Il trigger canonico è un’annotazione multimediale Screen o un’azione Rendition (ISO 32000-2:2020 §12.5.6.18 / §13.2) sotto un profilo di archiviazione PDF/A, vietate da ogni parte di PDF/A (serie ISO 19005) — il file fallirebbe la convalida veraPDF, perciò il motore rifiuta in anticipo.
• Contesto. getContext() restituisce conformance_mode (la modalità dichiarata, ad esempio pdfa4) e feature (la funzionalità rifiutata, ad esempio Screen annotation). Entrambe sono proprietà pubbliche readonly. Il motivo è il messaggio dell’eccezione.
• Recupero. Azione dello sviluppatore: eliminare la chiamata multimediale per l’output di archiviazione, oppure puntare a un profilo di conformità non di archiviazione (predefinito ConformanceMode::Plain).

PdfRViolationException

• Quando viene sollevata. Quando un’invariante di conformità PDF/R-1 (ISO 23504-1:2020) viene violata, sia alla costruzione del value object (i profili PdfRStrip, PdfRPage, PdfRDocument) sia al momento del validatore (PdfRValidator). Cattura la clausola normativa problematica e una descrizione della violazione su una riga, così che i consumatori di audit possano indirizzare i riscontri alla corretta sotto-clausola §6 senza analizzare testo libero.
• Contesto. getContext() restituisce standard (sempre ISO 23504-1:2020), clause (il percorso della clausola, ad esempio 6.6.1) e violation. Getter tipizzati: getClause(), getViolation().
• Recupero. Azione dello sviluppatore: correggere l’input rifiutato o ricostruire il documento per conformarlo alla clausola citata.

Generazione di codici a barre

BarcodeException

• Quando viene sollevata. Quando la generazione di codici a barre fallisce a causa di dati non validi o errori di codifica in tutte le simbologie supportate (Code 39/128, UPC-A/E, EAN-8/13, Interleaved/Standard 2-of-5, POSTNET, PLANET, MSI, ISBN, ISSN, QR Code, PDF417, DataMatrix, JabCode) e di guasti di rendering GD durante la creazione dell’immagine. Il valore del codice a barre viene troncato a 128 byte nel messaggio e nel contesto — payload troppo lunghi o binari vengono memorizzati troncati con un marcatore ... (<N> bytes, truncated) affinché non possano essere copiati per intero in un log.
• Contesto. getContext() restituisce barcode_type (simbologia, ad esempio QRCODE, EAN13, CODE128) e value (il valore troncato). Getter tipizzati: getBarcodeType(), getValue().
• Recupero. Azione dello sviluppatore: correggere i dati del codice a barre o la selezione della simbologia.

BarcodeEncoderNotFoundException

• Quando viene sollevata. Da BarcodeEncoderRegistry quando il tipo di encoder richiesto è sconosciuto oppure il suo gate di capacità è chiuso. Implementa inoltre PSR-11 Psr\Container\NotFoundExceptionInterface, perciò il registro è un container conforme agli standard. Il messaggio indica la simbologia e il motivo.
• Contesto. Non sovrascrive getContext(), quindi restituisce un array vuoto. Il type e il reason sono disponibili tramite i getter getType() e getReason() e nel messaggio.
• Recupero. Azione dello sviluppatore: registrare l’encoder, oppure installare il pacchetto che lo fornisce (ad esempio nextpdf/pro per Micro QR / DotCode / HanXin / JabCode).

Crittografia, cifratura e firme

EncryptionException

• Quando viene sollevata. Quando la cifratura o la decifratura PDF fallisce: guasti di encrypt/decrypt AES-256-CBC, errori OpenSSL, dimensioni IV non valide, guasti di calcolo dell’hash ed errori di calcolo dei valori UE/OE. In genere un’estensione OpenSSL mancante o mal configurata, materiale di chiave non valido o dati cifrati corrotti. Il messaggio indica l’operazione e l’algoritmo.
• Contesto. getContext() restituisce algorithm (ad esempio AES-256-CBC) e operation (ad esempio encrypt, decrypt, key_derivation). Getter tipizzati: getAlgorithm(), getOperation().
• Recupero. Azione dell’infrastruttura: assicurarsi che OpenSSL sia disponibile e configurato correttamente. Vedere Cifratura e permessi.

UnsupportedAlgorithmException

• Quando viene sollevata. Quando un algoritmo crittografico non può essere eseguito nel runtime corrente: un’estensione PHP necessaria non è disponibile, la libreria sottostante manca della primitiva, l’estensione hash inclusa non può sintetizzare una variante SHAKE/XOF, oppure l’algoritmo non è registrato nel SignatureAlgorithmRegistry. Il motore non deve degradare silenziosamente a una primitiva più debole, perciò fa emergere questo errore. Il factory statico nonFipsHostUnderFipsProfile() lo solleva (con identificatore di algoritmo regulatory-profile:fips) quando RegulatoryProfile::FIPS è selezionato ma non è possibile confermare un provider OpenSSL convalidato FIPS (sia FIPS_ABSENT sia INDETERMINATE adottano il fail-closed).
• Contesto. getContext() restituisce algorithm (nome o OID, ad esempio shake256, Ed25519, AES-256-GCM) e reason (azionabile dall’operatore). Getter tipizzati: getAlgorithm(), getReason().
• Recupero. Azione dell’operatore: installare l’estensione mancante o aggiornare il runtime; per il gate FIPS, installare una build OpenSSL convalidata FIPS oppure impostare esplicitamente NEXTPDF_FIPS_MODE. Azione dello sviluppatore: registrare un descrittore di algoritmo personalizzato tramite SignatureAlgorithmRegistry::register().

SignatureException

• Quando viene sollevata. Quando un’operazione di firma digitale fallisce: gestione di certificato e chiave privata (parsing PKCS#12, decodifica PEM/DER, convalida X.509), costruzione PKCS#7/CMS, formato della firma ECDSA, violazioni della dimensione del container, codifica DER e orchestrazione PAdES. Gli errori specifici della TSA sono segnalati invece dalla più specifica TsaException. Preferire i factory denominati tipizzati al costruttore posizionale; ciascuno collega la causa radice alla coda del messaggio. Esempi: ltvCapabilityMissing() (B-LT/B-LTA richiede nextpdf/enterprise), tsaRequired() / tsaUrlEmpty() / tsaEmptyToken(), httpClientMissing(), hsmSignerMissing() / hsmSignatureEmpty(), signatureContentsNotFound() / signatureContentsPaddingCorrupt(), unexpectedKeyType(), pemDecodingFailed(), la famiglia Ed25519 (ed25519SignatureMalformed(), ed25519RoundTripVerifyFailed(), ed25519KeyParseFailed(), ed25519SeedInvalid(), ed25519SecretKeyMalformed(), ed25519PublicKeyInvalid()), documentTimestampNotEmitted(), algorithmPolicyRejected(), digestOnlyAlgorithmRefused(), encryptedLtvUnsupported(), incrementalUpdateWriterMissing() e la coppia di stati OCSP nonSuccessfulOcspResponseStatus() / reservedOcspResponseStatus() (RFC 6960 §4.2.1). Questi factory adottano il fail-closed anziché emettere una firma silenziosamente declassata.
• Contesto. getContext() restituisce cert_info (subject DN o impronta digitale, oppure vuoto), signature_level (il livello PAdES tentato, ad esempio B-B, B-T, B-LT, B-LTA) e detail (la diagnosi azionabile, vuota per il costruttore posizionale legacy). Getter tipizzati: getCertInfo(), getSignatureLevel(), getDetail().
• Recupero. Azione dello sviluppatore: correggere la configurazione di certificato/chiave. Per i factory di capacità mancante, installare il pacchetto indicato. Vedere Errori di firma e marca temporale per le voci di sintomo e risoluzione relative a ciascun factory.

BlackPointCompensationUnsupportedException

• Quando viene sollevata. Da NullBlackPointCompensationTransform::transform() quando un chiamante chiede all’adattatore null di applicare una trasformazione di compensazione del punto di nero ISO 18619 diversa da Default. L’adattatore null è il fallback sicuro per ambienti privi di un backend di gestione del colore; produrre un campione trasformato senza un vero modulo di gestione del colore segnalerebbe silenziosamente in modo errato la conversione. A differenza della maggior parte delle voci qui presenti, questa estende direttamente \RuntimeException, non NextPdfException, perciò i percorsi catch (\RuntimeException) esistenti continuano a funzionare.
• Contesto. Nessun getContext(); è una semplice \RuntimeException. Il dettaglio è nel messaggio.
• Recupero. Azione dello sviluppatore: registrare un vero BlackPointCompensationTransform (LittleCMS, Argyll, pure-PHP), oppure limitare /UseBlackPtComp a BlackPointCompensation::Default.

Assemblaggio del documento e accessibilità

UnsupportedSourceDocumentException

• Quando viene sollevata. Quando un documento di origine non può essere copiato in modo sicuro in un output di unione/divisione e l’operazione adotta il fail-closed anziché emettere un risultato corrotto o compromesso sul piano della sicurezza. Usare i factory denominati: encrypted() (ISO 32000-2 §7.6 — il contenuto non può essere copiato senza la chiave), signed() (§12.8 — copiare le pagine invaliderebbe il byte range della firma), unsupportedStreamFilter() (un filtro che il reader del grafo di oggetti non può rielaborare round-trip), multipleInteractiveForms() (una limitazione documentata: più di un’origine trasporta un /AcroForm non vuoto, §12.7) e splitWithInteractiveForm() (una limitazione documentata: sottoinsiemizzare le pagine di un’origine con form lascerebbe orfani i widget). Estende direttamente \RuntimeException, non NextPdfException.
• Contesto. Nessun getContext(); è una semplice \RuntimeException. La causa e il numero dell’oggetto interessato sono indicati nel messaggio.
• Recupero. Azione dello sviluppatore: decifrare prima l’origine oppure fornire la chiave; per le origini firmate, firmare dopo l’unione; per le unioni multi-form, appiattire o rimuovere i campi form di tutte le origini tranne una; per le divisioni di origini con form, appiattire il form prima di dividere.

InvalidBcp47TagException

• Quando viene sollevata. Da Bcp47Validator::validate() quando un tag di lingua candidato è malformato secondo l’ABNF di RFC 5646 §2.1, oppure fallisce la ricerca nel registro curato. Specifico del dominio BCP-47 / ISO 14289-2:2024 §8.4.4, distinto da InvalidConfigException così che i chiamanti a valle del confine di accessibilità possano intercettare un tipo ristretto. La coppia di predicati Bcp47Validator::isWellFormed() / isValid() rimane la superficie di valore di ritorno retrocompatibile per i chiamanti che preferiscono diramare anziché usare le eccezioni.
• Contesto. getContext() restituisce tag (il candidato esattamente come fornito) e reason (un codice di rifiuto stabile e leggibile a macchina, ad esempio empty-string, well-formed-shape, unregistered-primary, duplicate-variant). Getter tipizzati: getTag(), getReason().
• Recupero. Azione dello sviluppatore: correggere il tag di lingua portandolo a un tag BCP-47 ben formato e registrato. Vedere Font e tagging.

FormFieldAccessibilityException

• Quando viene sollevata. Quando un campo di un form interattivo si baserebbe su un nome accessibile sintetico (non fornito dall’autore) durante la produzione di un documento PDF/UA con l’applicazione strict del nome accessibile dei campi abilitata. L’output PDF/UA predefinito emette un nome di fallback sintetico nel /Contents del widget, così che un campo non sia mai privo di nome; la modalità strict richiede invece che l’autore fornisca un nome significativo (un tooltip, o una didascalia per un pulsante senza azione) affinché gli utenti di screen reader ottengano una descrizione reale (ISO 14289-2:2024 §8.10.2).
• Contesto. Non sovrascrive getContext(), quindi restituisce un array vuoto. Il $fieldId è una proprietà pubblica readonly; il motivo è il messaggio.
• Recupero. Azione dello sviluppatore: fornire un tooltip / nome accessibile per il campo indicato prima di produrre un documento PDF/UA strict, oppure disabilitare la modalità strict. Vedere Convalida PDF/A e PDF/UA.

VendorExtensionRegistryConflictException

• Quando viene sollevata. Da VendorExtensionRegistry::register() quando un chiamante registra di nuovo un prefisso vendor di estensione developer PDF noto (ISO 32000-2:2020 §7.12.1) con una descrizione che diverge dai metadati già registrati. I descrittori sono append-only e con rilevamento dei conflitti; l’eccezione tipizzata ha sostituito una \RuntimeException generica così che i chiamanti possano intercettare questa classe specifica.
• Contesto. getContext() restituisce prefix, existing_description e attempted_description. Getter tipizzati: getPrefix(), getExistingDescription(), getAttemptedDescription().
• Recupero. Azione dello sviluppatore: registrare il prefisso con la descrizione esistente, oppure usare un prefisso distinto; non sovrascrivere i metadati registrati.

Esportazione di audit

AuditExportException

• Quando viene sollevata. Quando l’assemblaggio del bundle di esportazione di audit, la generazione della matrice di tracciabilità o la proiezione dello schema falliscono a runtime. Copre l’I/O su claims.json / manifest.json, l’encode/decode JSON del bundle canonico e la mancata corrispondenza della versione di schema sul percorso retrocompatibile AuditExporter::projectToV1(). Il messaggio indica la fase, l’artefatto quando noto e il dettaglio.
• Contesto. getContext() restituisce stage (ad esempio read_claims, encode_bundle, project_v1), detail e artefact (percorso o schema_version che ha innescato il guasto). Getter tipizzati: getStage(), getDetail(), getArtefact().
• Recupero. Azione di compliance / DevOps: verificare i percorsi degli artefatti di input, rigenerare claims.json da un’esecuzione pulita, oppure ricostruire il manifest prima di ritentare l’esportazione.

Value object di violazione

Questi non sono eccezioni. Sono value object immutabili restituiti dal motore per descrivere una singola violazione; non trasportano alcun getContext().

ComplianceViolation

• Che cos’è. Un value object final readonly che rappresenta un singolo fallimento di regola segnalato da un validatore esterno (veraPDF o equivalente), incluso il riferimento alla clausola ISO e la posizione all’interno della struttura del PDF.
• Campi. Proprietà pubbliche readonly: ruleId (identificatore della regola del validatore, ad esempio 6.1.2-1), clause (riferimento alla clausola ISO, ad esempio ISO 19005-1:2005, 6.1.2), severity (ad esempio error, warning), location (percorso dell’oggetto all’interno della struttura del PDF) e message (descrizione leggibile).
• Uso. Ispezionare la collezione restituita da un validatore di conformità; indirizzare o visualizzare ogni voce in base a severity e clause. Vedere Convalida PDF/A e PDF/UA.

RuleViolation

• Che cos’è. Un value object final readonly che rappresenta una singola violazione di regola di business Schematron / EN 16931, restituita da SchematronRunnerInterface::runRules() e aggregata all’interno di ValidationResult::$ruleViolations. La stabilità è experimental.
• Campi. Proprietà pubbliche readonly: ruleId (identificatore EN 16931 come BR-{n}, BR-CO-{n}, BR-CL-{n}, BR-DEC-{n}, o un pacchetto specifico di tier), severity (un enum RuleSeverity), message (testo della regola, en-GB), xpath (XPath nell’XML incorporato, null per le regole valide sull’intero documento) e semanticPath (percorso BG/BT in notazione punto come BG-22.BT-106, null per le violazioni strutturali).
• Uso. Ispezionare la collezione sul risultato di convalida; indirizzare o visualizzare ogni voce in base a severity, ruleId e localizzatore.

Vedere anche

• Indice del riferimento degli errori
• Indice della knowledge base
• Errori di firma e marca temporale
• Cifratura e permessi
• Font e tagging
• Convalida PDF/A e PDF/UA