Core- en algemene fouten

Reikwijdte

Deze vermeldingen behandelen de core- en algemene uitzonderingen die NextPDF opwerpt. De meeste breiden de basis NextPdfException uit, die zelf \RuntimeException uitbreidt en ContextAwareExceptionInterface implementeert. Die interface stelt één methode beschikbaar, getContext(): array, die een platte snake_case-map van primitieven teruggeeft die veilig is om naar een log of APM-payload te serialiseren.

Vang de NextPdfException-familie op met één enkele catch (NextPdfException $e). Voeg ook een catch (\RuntimeException $e) toe om de enkele laag-niveau-fouten in deze verzameling te dekken die \RuntimeException rechtstreeks uitbreiden (hieronder vermeld). De basis NextPdfException::getContext() geeft een lege array terug; subklassen overschrijven hem om domeinvelden toe te voegen. Waar een klasse getContext() niet overschrijft, erft hij de lege array en leeft het diagnostische detail in plaats daarvan in het bericht en de getypeerde getters.

Vier types in deze verzameling breiden NextPdfException niet uit: BlackPointCompensationUnsupportedException en UnsupportedSourceDocumentException breiden \RuntimeException rechtstreeks uit (vang ze op als \RuntimeException), en ComplianceViolation en RuleViolation zijn value objects, geen uitzonderingen — zij worden hier gedocumenteerd omdat ze de fout- en overtredingsdata modelleren die de engine teruggeeft.

Basisuitzondering

NextPdfException

• Wat het is. abstract basis voor de belangrijkste NextPDF-uitzonderingsfamilie over core en zijn extensiepakketten. Hij breidt \RuntimeException uit en implementeert ContextAwareExceptionInterface. Het opvangen van dit ene type onderschept de NextPdfException-familie; de enkele fouten die \RuntimeException rechtstreeks uitbreiden (hierboven vermeld) hebben ook een \RuntimeException-catch nodig.
• Context. De basis getContext() geeft een lege array terug. Subklassen overschrijven hem om domeinspecifieke velden terug te geven.
• Herstel. Wordt niet rechtstreeks opgeworpen. Gebruik hem als het catch-all-type; vertak op de concrete subklasse voor specifieke afhandeling.

Configuratie en feature-gating

InvalidConfigException

• Wanneer hij wordt opgeworpen. Wanneer een Config-waarde of combinatie van waarden ongeldig is — een ontbrekende verplichte instelling, een wederzijds uitsluitende optie, of een waarde buiten het geaccepteerde bereik. Dit duidt op een ontwikkelaarsfout: de aanroepende code leverde een configuratie die moet worden gecorrigeerd vóór een nieuwe poging. Het bericht rapporteert de sleutel, het verwachte type of bereik en het werkelijke debug-type van de geleverde waarde.
• Context. getContext() geeft config_key, given_value en expected_type terug. Getypeerde getters: getConfigKey(), getGivenValue(), getExpectedType().
• Herstel. Ontwikkelaarsactie: corrigeer de genoemde configuratiesleutel naar een waarde van het verwachte type of bereik voordat je NextPDF opnieuw aanroept.

NotImplementedException

• Wanneer hij wordt opgeworpen. Wanneer een openbaar API-toegangspunt wordt bereikt maar zijn implementatie opzettelijk afwezig is in de huidige release. Gebruikt voor deprecated shims die bestaan om pre-bisect-aanroepers een luide, actiegerichte storing te geven in plaats van een stille no-op. Het bericht combineert een machine-grepbaar feature-label en een followUp-verwijzing (defect-ID, tracking-anker of sprintnaam).
• Context. Overschrijft getContext() niet, dus geeft hij een lege array terug. De waarden $feature en $followUp zijn publieke readonly properties en zijn ingebed in het bericht.
• Herstel. Bibliotheekaanroeper-actie: verwijder de aanroep, of pin naar een toekomstige release die de genoemde follow-up landt.

IncompatibleFeatureFlagsException

• Wanneer hij wordt opgeworpen. Bij het bouwen van Config (Config::validate()) wanneer een CssFeatureFlags-combinatie intern inconsistent is — de ene flag veronderstelt een andere die uitgeschakeld is. De enige verboden combinatie vandaag is layoutSubgrid = true met layoutGrid = false: een gesubgridde as ontleent zijn rasterlijnen aan een bovenliggende rastercontainer (CSS Grid Layout Module Level 2 §1), dus subgrid zonder grid beschrijft een raster dat niet kan bestaan. De controle draait op de resolved flags, dus CssRenderingMode::Safe (die elke Phase 4+-feature afdwingt om uit te staan) maskeert de combinatie in plaats van hem te activeren. Breidt StrictModeViolation uit.
• Context. getContext() voegt de bovenliggende strict-modus-velden (cssDeviation, excId, chunkSha256, location) samen met de booleans layoutGrid en layoutSubgrid. De location is Config::validate() en cssDeviation codeert het flag-paar.
• Herstel. Bibliotheekaanroeper-actie: schakel layoutGrid in naast layoutSubgrid, of schakel layoutSubgrid uit.

IncompatibleRenderingModeException

• Wanneer hij wordt opgeworpen. Bij het bouwen van Config wanneer een combinatie van CssRenderingMode en CssLayoutMode buiten de compatibele cellen van de modusmatrix valt. De enige verboden combinatie vandaag is CssRenderingMode::Safe + CssLayoutMode::Retained — Safe dwingt elke Phase 4+-feature af om uit te staan, waardoor retained-modus-formatteringscontexten (Grid, Subgrid, @container) geen consumers overhouden, dus de combinatie wordt afgewezen in plaats van toegestaan om stil te degraderen. Breidt StrictModeViolation uit.
• Context. getContext() voegt de bovenliggende strict-modus-velden samen met mode1 (de rendering-modus-waarde) en mode2 (de lay-out-modus-waarde). De cssDeviation codeert het moduspaar; location is Config::validate().
• Herstel. Bibliotheekaanroeper-actie: kies Safe + Streaming voor rollback, of een niet-Safe rendering-modus (Normal / Strict / Audit) met Retained voor Grid / Subgrid / Container Queries.

StrictModeViolation

• Wanneer hij wordt opgeworpen. abstract basis voor elke spec-afwijking-uitzondering die wordt opgeworpen onder CssRenderingMode::Strict. In strict-modus werpt elke gedetecteerde CSS-afwijking die niet gekoppeld is aan een geregistreerde EXC-NNN-uitzonderingsvermelding een instantie van deze klasse (of een subklasse) op op het detectiepunt. Wordt niet rechtstreeks opgeworpen; zie IncompatibleFeatureFlagsException en IncompatibleRenderingModeException.
• Context. getContext() geeft de vier ADR-023-velden terug: cssDeviation (korte label voor het afwijkende construct), excId (registry-identifier wanneer geregistreerd, anders null), chunkSha256 (spec-citaat-chunk-hash indien bekend, anders null) en location (door de aanroeper leesbare oorsprong, anders null).
• Herstel. Bibliotheekaanroeper-actie: registreer de afwijking als een nieuwe ondertekende EXC-NNN-vermelding, of corrigeer de renderer om de afwijking te verwijderen.

HTML- en CSS-invoer

HtmlParsingException

• Wanneer hij wordt opgeworpen. Wanneer het parsen van HTML-invoer of de DOM-constructie faalt: ongeldige charset-declaraties, overtredingen van de invoergrootte-limiet, overmatige nestingsdiepte, element-aantal-overflows en tabelstructuurfouten zoals een maximaal rij-aantal. CSS-specifieke resource-uitputting wordt in plaats daarvan gerapporteerd door CssParserLimitExceededException en CssResolutionBudgetExceededException.
• Context. getContext() geeft html_snippet (een kort, afgekapt fragment van de overtredende HTML), position (byte-offset, of -1 indien onbekend) en rule (de overtreden parser-beperking) terug. Getypeerde getters: getHtmlSnippet(), getPosition(), getRule().
• Herstel. Ontwikkelaarsactie: vereenvoudig de HTML-invoer of pas de parser-limieten aan.

CssParserLimitExceededException

• Wanneer hij wordt opgeworpen. Wanneer CSS-invoer een geconfigureerde parser-veiligheidslimiet overschrijdt. Twee categorieën worden gedekt via de benoemde constructors: forByteLimit() (stylesheet te groot voor veilige regex-verwerking) en forNestingDepth() (CSS-nesting-recursie te diep). Beide berichten noemen de werkelijke waarde en de limiet.
• Context. getContext() geeft limit_type (byte of nesting_depth), actual en limit terug.
• Herstel. Ontwikkelaarsactie: splits de stylesheet in kleinere sheets, of verminder de nestingsdiepte, of verhoog de geconfigureerde limiet.

CssResolutionBudgetExceededException

• Wanneer hij wordt opgeworpen. Wanneer de CSS-:has()-resolutie haar traversal-budget overschrijdt. De tweepass-:has()-resolver dwingt een strikt node-bezoek-budget af om te voorkomen dat pathologische selectors kwadratische documentdoorlopen veroorzaken; zodra het totale bezoekaantal de limiet overschrijdt, wordt de stylesheet als te complex afgewezen. Het bericht noemt het bezoekaantal en het budget.
• Context. getContext() geeft visits en budget terug. Getypeerde getters: getVisits(), getBudget().
• Herstel. Ontwikkelaarsactie: verminder de selectorcomplexiteit, of verhoog het geconfigureerde budget.

Lettertypen en afbeeldingen

FontNotFoundException

• Wanneer hij wordt opgeworpen. Wanneer een lettertypebestand niet kan worden gelokaliseerd of gelezen op bestandssysteemniveau: de gevraagde familie of het pad bestaat niet, is niet leesbaar, of de geconfigureerde lettertypedirectory is ontoegankelijk. De lettertypedata kan geldig zijn — dit duidt er alleen op dat hij niet bereikbaar is. Het bericht somt de doorzochte paden op.
• Context. getContext() geeft font_name, search_paths (een lijst) en fallback_attempted (een bool) terug. Getypeerde getters: getFontName(), getSearchPaths(), wasFallbackAttempted().
• Herstel. Ontwikkelaarsactie: verifieer het lettertypepad. Infrastructuuractie: herstel de bestandsmachtigingen op het lettertypebestand of de directory.

FontParsingException

• Wanneer hij wordt opgeworpen. Wanneer een lettertypebestand wordt gevonden maar de inhoud ervan niet bruikbaar is: het is beschadigd, in een niet-ondersteund formaat, of mist vereiste tabellen. Dekt structurele validatiestoringen tijdens het parsen van TrueType, Type 1, CFF en OpenType — afgekapte headers, ongeldige tabeldirectory’s, ontbrekende verplichte tabellen (head, hhea, OS/2), uitpakfouten en grootte- overtredingen. Het bericht noemt het bestand en de parse-fout.
• Context. getContext() geeft font_file en parse_error terug. Getypeerde getters: getFontFile(), getParseError().
• Herstel. Ontwikkelaarsactie: vervang het lettertypebestand door een geldig bestand.

ImageProcessingException

• Wanneer hij wordt opgeworpen. Wanneer een afbeelding niet kan worden gedecodeerd, in een niet-ondersteund formaat is, of GD/Imagick-verwerking faalt: onherkenbare magic bytes, beschadigde JPEG-data, niet-ondersteunde MIME-types, overtredingen van de bestandsgrootte-limiet en GD-resource- allocatiestoringen. De afbeelding was toegankelijk maar de pixeldata kon niet worden geëxtraheerd voor inbedding.
• Context. getContext() geeft image_path (leeg voor inline data), format (gedetecteerd of verwacht, bijv. jpeg, png, unknown) en operation (bijv. decode, resize, embed) terug. Getypeerde getters: getImagePath(), getFormat(), getOperation().
• Herstel. Ontwikkelaarsactie: lever een geldig, ondersteund afbeeldingsbestand.

Uitvoer, lay-out en serialisatie

CompressionException

• Wanneer hij wordt opgeworpen. Wanneer FlateDecode (zlib)-compressie of -decompressie faalt — gzcompress/gzuncompress-storingen op content streams, lettertypedata, pagina-inhoud, bijlagedata en cross-reference streams. Doorgaans een beschadigde invoerstream, onvoldoende geheugen, of een ontbrekende zlib-extensie.
• Context. getContext() geeft algorithm (filternaam, bijv. FlateDecode, LZWDecode) en stream_length (bytelengte, of -1 indien onbekend) terug. Getypeerde getters: getAlgorithm(), getStreamLength().
• Herstel. Infrastructuuractie: verifieer dat ext-zlib is geladen en dat het geheugen toereikend is.

WriterException

• Wanneer hij wordt opgeworpen. Wanneer PDF-serialisatie, linearisatie of I/O-uitvoer faalt: PdfWriter-stream-schrijffouten, corruptie van de cross-reference-tabel, header-/trailer-generatiestoringen, object-referentie-resolutiestoringen, bestands- schrijffouten en uitvoerbuffer-overflows. Een geldig in-memory-document kon niet worden geserialiseerd naar een geldige bytestream. Het bericht noemt de fase.
• Context. getContext() geeft output_path (leeg voor string-uitvoer) en writer_state (de fase, bijv. header, body, xref, trailer) terug. Getypeerde getters: getOutputPath(), getWriterState().
• Herstel. Infrastructuuractie: controleer schijfruimte, bestandsmachtigingen en de uitvoerstream.

PageLayoutException

• Wanneer hij wordt opgeworpen. Wanneer aan pagina-lay-out-beperkingen niet kan worden voldaan: kolomlay-out-overtredingen (onvoldoende breedte, ongeldig kolomaantal), inhouds- overflow buiten de paginagrenzen en margeconflicten. De gevraagde lay-out is geometrisch onmogelijk voor de gegeven pagina-afmetingen en -inhoud. Het bericht noemt het paginanummer indien bekend en de overtreden beperking.
• Context. getContext() geeft page_number (één-gebaseerd, of 0 indien onbekend) en constraint terug. Getypeerde getters: getPageNumber(), getConstraint().
• Herstel. Ontwikkelaarsactie: pas paginagrootte, marges, kolominstellingen of inhoud aan.

TemplateException

• Wanneer hij wordt opgeworpen. Wanneer een PDF-template-import- of hergebruikbewerking faalt in TemplateManager: ongeldige template-statusovergangen (templates buiten volgorde beginnen of beëindigen), het verwijzen naar een niet-bestaande template, en stream- compressiestoringen tijdens template-serialisatie. Het bericht noemt de bewerking en de template-id wanneer toegewezen.
• Context. getContext() geeft template_id (leeg indien nog niet toegewezen) en operation (bijv. begin, end, use, serialize) terug. Getypeerde getters: getTemplateId(), getOperation().
• Herstel. Ontwikkelaarsactie: corrigeer de template-gebruiksvolgorde of de bron- PDF.

Content-stream-invarianten

ContentStreamBalanceException

• Wanneer hij wordt opgeworpen. Wanneer een ContentStreamBuilder een onbalans in een operatorpaar detecteert bij het sluiten van de stream (of midden in de stream wanneer invarianten gretig worden geasserteerd). Hij legt de diepte-tellers vast die de balans-invariant faalden zodat logging kan identificeren welke emitter een q, BT of BMC lekte zonder zijn bijbehorende Q, ET of EMC. Per ISO 32000-2:2020 §8.4.2 (graphics-state- stack), §9.4.1 (text objects) en §14.6 (marked content).
• Context. getContext() geeft graphics_depth, text_block_depth, marked_content_depth en offending_operator terug. Getypeerde getters: getGraphicsDepth(), getTextBlockDepth(), getMarkedContentDepth(), getOffendingOperator().
• Herstel. Ontwikkelaarsactie: lokaliseer de emitter die een construct opende zonder het te sluiten.

GraphicsStateBalanceException

• Wanneer hij wordt opgeworpen. Wanneer een PDF-content-stream sluit met ongebalanceerde q/Q- operators. ISO 32000-2:2020 §8.4.2 vereist dat elke graphics-state-save (q) wordt afgesloten met precies één restore (Q) voordat de stream eindigt; onbalans lekt transform, clipping path, kleuren en rendering intent naar volgende pagina’s of Form XObjects. Wordt alleen opgeworpen wanneer strikte graphics-state-controle is ingeschakeld (NEXTPDF_GFXSTATE_STRICT=1); in relaxed modus wordt in plaats daarvan een waarschuwing afgegeven via trigger_error().
• Context. getContext() geeft save_depth terug (positief voor te veel saves, negatief voor te veel restores). Getypeerde getter: getSaveDepth().
• Herstel. Ontwikkelaarsactie: lokaliseer het niet-afgesloten save()/restore()- paar.

MissingShadingResourceException

• Wanneer hij wordt opgeworpen. Wanneer ConicGradientRenderer::render() wordt aangeroepen zonder een Shading-resource-registry-context. De breaking change in v10.0.0 verwijderde het eerdere impliciete-marker-map-surrogaatpad: aanroepers moeten de renderer construeren met een ShadingResourceRegistryInterface zodat het /ShadingType 4- indirecte object wordt geregistreerd tegen de Shading-resource- subdictionary van de pagina (ISO 32000-2 §8.7.4.2 / §8.7.4.3). Het bericht noemt de aanroeper- context en wijst naar de v9.x→v10.0-migratienotitie.
• Context. getContext() geeft context terug (een korte aanroeper-context-label, bijv. ConicGradientRenderer::render).
• Herstel. Bibliotheekaanroeper-actie: bedraad een Shading-resource-registry-instantie in de renderer-constructor voordat je render() aanroept.

Linearisatie (Fast Web View)

LinearizationInvariantException

• Wanneer hij wordt opgeworpen. Wanneer de v2-driepass-Linearizer detecteert dat zijn MEASURE → PLACE → FILL-asserties zijn overtreden: een Pass 3-byte-aantal dat niet overeenkomt met de in Pass 1 voorspelde bestandslengte (offset drift), een linearisatie- dictionary-placeholder die te klein is voor de geserialiseerde breedte, of een /H [offset length]-hint-stream-offset die niet overeenkomt met de uiteindelijke uitvoer. Dit aan de oppervlakte brengen in plaats van een kapotte PDF uitvoeren is een verklaarde veiligheidsgarantie.
• Context. getContext() geeft invariant (de naam van de overtreden invariant), expected, actual en delta (het ondertekende verschil) terug. Getypeerde getters: getInvariant(), getExpectedValue(), getActualValue().
• Herstel. Maintainer-actie: dien een bugrapport in — deze invarianten zouden moeten gelden voor alle welgevormde invoer. Leg de geketende vorige uitzondering vast.

LinearizationUnimplementedException

• Wanneer hij wordt opgeworpen. Wanneer de linearizer-feature-flag is ingesteld op een backend die opzettelijk is uitgeschakeld. Wordt momenteel alleen opgeworpen voor linearizerVersion === 'v1-noop', de emergency-downgrade-instelling die alle linearisatiepogingen tijdens runtime afwijst zonder een codewijziging of herdeploy — nuttig om Fast Web View in productie met een kill-switch uit te schakelen.
• Context. getContext() geeft reason terug (een korte voor mensen leesbare uitleg). Getypeerde getter: getReason().
• Herstel. Operator-/release-engineering-actie: pas de configuratie aan of upgrade naar een gefixte backend-versie.

Conformiteits- en profiel-invarianten

ConformanceViolationException

• Wanneer hij wordt opgeworpen. Wanneer een gevraagde feature niet kan worden uitgevoerd zonder het verklaarde ISO-conformiteitscontract van het document te breken, en de engine fail-closed gaat in plaats van een niet-conform object te schrijven. De canonieke trigger is een multimedia-Screen-annotatie of Rendition-actie (ISO 32000-2:2020 §12.5.6.18 / §13.2) onder een PDF/A-archiveringsprofiel, wat elk PDF/A-deel verbiedt (ISO 19005-serie) — het bestand zou de veraPDF-validatie falen, dus de engine weigert vooraf.
• Context. getContext() geeft conformance_mode (de verklaarde modus, bijv. pdfa4) en feature (de afgewezen feature, bijv. Screen annotation) terug. Beide zijn publieke readonly properties. De reden is het uitzonderingsbericht.
• Herstel. Ontwikkelaarsactie: laat de multimedia-aanroep vallen voor archiveringsuitvoer, of richt je op een niet-archiverend conformiteitsprofiel (standaard ConformanceMode::Plain).

PdfRViolationException

• Wanneer hij wordt opgeworpen. Wanneer een PDF/R-1 (ISO 23504-1:2020)-conformiteitsinvariant wordt overtreden, ofwel bij de constructie van een value object (de profielen PdfRStrip, PdfRPage, PdfRDocument) of bij validatietijd (PdfRValidator). Hij legt de overtredende normatieve clausule en een eenregelige overtredingsbeschrijving vast zodat audit- consumers bevindingen kunnen routeren naar de juiste §6-subclausule zonder vrije tekst te parsen.
• Context. getContext() geeft standard (altijd ISO 23504-1:2020), clause (het clausulepad, bijv. 6.6.1) en violation terug. Getypeerde getters: getClause(), getViolation().
• Herstel. Ontwikkelaarsactie: corrigeer de afgewezen invoer of herbouw het document zodat het voldoet aan de geciteerde clausule.

Barcodegeneratie

BarcodeException

• Wanneer hij wordt opgeworpen. Wanneer barcodegeneratie faalt door ongeldige data of coderingsfouten over alle ondersteunde symbologieën (Code 39/128, UPC-A/E, EAN-8/13, Interleaved/Standard 2-of-5, POSTNET, PLANET, MSI, ISBN, ISSN, QR Code, PDF417, DataMatrix, JabCode), en GD-renderingstoringen tijdens de aanmaak van de afbeelding. De barcodewaarde wordt in het bericht en de context begrensd tot een fragment van 128 bytes — te lange of binaire payloads worden afgekapt opgeslagen met een ... (<N> bytes, truncated)-markering zodat ze niet in hun geheel in een log kunnen worden gekopieerd.
• Context. getContext() geeft barcode_type (symbologie, bijv. QRCODE, EAN13, CODE128) en value (de afgekapte waarde) terug. Getypeerde getters: getBarcodeType(), getValue().
• Herstel. Ontwikkelaarsactie: corrigeer de barcodedata of de symbologie- selectie.

BarcodeEncoderNotFoundException

• Wanneer hij wordt opgeworpen. Vanuit BarcodeEncoderRegistry wanneer het gevraagde encoder- type onbekend is of zijn capability-gate gesloten is. Hij implementeert ook PSR-11 Psr\Container\NotFoundExceptionInterface, dus de registry is een standaard-conforme container. Het bericht noemt de symbologie en de reden.
• Context. Overschrijft getContext() niet, dus geeft hij een lege array terug. De type en reason zijn beschikbaar via de getters getType() en getReason() en in het bericht.
• Herstel. Ontwikkelaarsactie: registreer de encoder, of installeer het pakket dat hem levert (bijvoorbeeld nextpdf/pro voor Micro QR / DotCode / HanXin / JabCode).

Cryptografie, versleuteling en handtekeningen

EncryptionException

• Wanneer hij wordt opgeworpen. Wanneer PDF-versleuteling of -ontsleuteling faalt: AES-256-CBC- encrypt-/decrypt-storingen, OpenSSL-fouten, ongeldige IV-groottes, hash-berekenings- storingen en UE-/OE-waardeberekeningsfouten. Doorgaans een ontbrekende of verkeerd geconfigureerde OpenSSL-extensie, ongeldig sleutelmateriaal, of beschadigde versleutelde data. Het bericht noemt de bewerking en het algoritme.
• Context. getContext() geeft algorithm (bijv. AES-256-CBC) en operation (bijv. encrypt, decrypt, key_derivation) terug. Getypeerde getters: getAlgorithm(), getOperation().
• Herstel. Infrastructuuractie: zorg dat OpenSSL beschikbaar en correct geconfigureerd is. Zie Versleuteling en machtigingen.

UnsupportedAlgorithmException

• Wanneer hij wordt opgeworpen. Wanneer een cryptografisch algoritme niet kan worden uitgevoerd in de huidige runtime: een vereiste PHP-extensie is niet beschikbaar, de onderliggende bibliotheek mist de primitieve, de meegeleverde hash-extensie kan geen SHAKE/XOF-variant synthetiseren, of het algoritme is niet geregistreerd in de SignatureAlgorithmRegistry. De engine mag niet stilletjes degraderen naar een zwakkere primitieve, dus brengt hij dit in plaats daarvan aan de oppervlakte. De statische factory nonFipsHostUnderFipsProfile() werpt hem op (met algoritme-identifier regulatory-profile:fips) wanneer RegulatoryProfile::FIPS is geselecteerd maar een FIPS-gevalideerde OpenSSL-provider niet kan worden bevestigd (zowel FIPS_ABSENT als INDETERMINATE gaan fail-closed).
• Context. getContext() geeft algorithm (naam of OID, bijv. shake256, Ed25519, AES-256-GCM) en reason (operator-actiegericht) terug. Getypeerde getters: getAlgorithm(), getReason().
• Herstel. Operator-actie: installeer de ontbrekende extensie of upgrade de runtime; voor de FIPS-gate, installeer een FIPS-gevalideerde OpenSSL-build of stel NEXTPDF_FIPS_MODE expliciet in. Ontwikkelaarsactie: registreer een aangepaste algoritme- descriptor via SignatureAlgorithmRegistry::register().

SignatureException

• Wanneer hij wordt opgeworpen. Wanneer een digitale-handtekeningbewerking faalt: certificaat- en private-key-afhandeling (PKCS#12-parsen, PEM/DER-decodering, X.509- validatie), PKCS#7/CMS-constructie, ECDSA-handtekeningformaat, container-grootte- overtredingen, DER-codering en PAdES-orchestratie. TSA-specifieke fouten worden in plaats daarvan gerapporteerd door de meer specifieke TsaException. Geef de voorkeur aan de getypeerde benoemde factories boven de positionele constructor; elke bindt de grondoorzaak aan de berichtstaart. Voorbeelden: ltvCapabilityMissing() (B-LT/B-LTA heeft nextpdf/enterprise nodig), tsaRequired() / tsaUrlEmpty() / tsaEmptyToken(), httpClientMissing(), hsmSignerMissing() / hsmSignatureEmpty(), signatureContentsNotFound() / signatureContentsPaddingCorrupt(), unexpectedKeyType(), pemDecodingFailed(), de Ed25519-familie (ed25519SignatureMalformed(), ed25519RoundTripVerifyFailed(), ed25519KeyParseFailed(), ed25519SeedInvalid(), ed25519SecretKeyMalformed(), ed25519PublicKeyInvalid()), documentTimestampNotEmitted(), algorithmPolicyRejected(), digestOnlyAlgorithmRefused(), encryptedLtvUnsupported(), incrementalUpdateWriterMissing(), en het OCSP-statuspaar nonSuccessfulOcspResponseStatus() / reservedOcspResponseStatus() (RFC 6960 §4.2.1). Deze factories gaan fail-closed in plaats van een stilletjes naar een lager niveau gebrachte handtekening uit te voeren.
• Context. getContext() geeft cert_info (subject-DN of thumbprint, of leeg), signature_level (het geprobeerde PAdES-niveau, bijv. B-B, B-T, B-LT, B-LTA) en detail (de actiegerichte diagnose, leeg voor de legacy positionele constructor) terug. Getypeerde getters: getCertInfo(), getSignatureLevel(), getDetail().
• Herstel. Ontwikkelaarsactie: corrigeer de certificaat-/sleutelconfiguratie. Voor capability-missing-factories, installeer het genoemde pakket. Zie Handtekening- en tijdstempelstoringen voor symptoom-en-oplossing-vermeldingen per factory.

BlackPointCompensationUnsupportedException

• Wanneer hij wordt opgeworpen. Vanuit NullBlackPointCompensationTransform::transform() wanneer een aanroeper de null-adapter vraagt om een niet-Default ISO 18619- black-point-compensation-transform toe te passen. De null-adapter is de veilige fallback voor omgevingen zonder een color-management-backend; een getransformeerd sample produceren zonder een echte color-management-module zou de conversie stilletjes verkeerd rapporteren. Anders dan de meeste vermeldingen hier, breidt deze \RuntimeException rechtstreeks uit, niet NextPdfException, dus bestaande catch (\RuntimeException)-paden blijven werken.
• Context. Geen getContext(); het is een gewone \RuntimeException. Het detail staat in het bericht.
• Herstel. Ontwikkelaarsactie: registreer een echte BlackPointCompensationTransform (LittleCMS, Argyll, pure-PHP), of beperk /UseBlackPtComp tot BlackPointCompensation::Default.

Documentassemblage en toegankelijkheid

UnsupportedSourceDocumentException

• Wanneer hij wordt opgeworpen. Wanneer een brondocument niet veilig kan worden gekopieerd naar een merge-/split-uitvoer en de bewerking fail-closed gaat in plaats van een beschadigd of qua beveiliging gecompromitteerd resultaat uit te voeren. Gebruik de benoemde factories: encrypted() (ISO 32000-2 §7.6 — inhoud kan niet worden gekopieerd zonder de sleutel), signed() (§12.8 — pagina’s kopiëren zou de signature byte range ongeldig maken), unsupportedStreamFilter() (een filter dat de object-graph-reader niet kan round-trippen), multipleInteractiveForms() (een gedocumenteerde beperking: meer dan één bron draagt een niet-lege /AcroForm, §12.7), en splitWithInteractiveForm() (een gedocumenteerde beperking: het paginasubsetten van een formulier-dragende bron zou widgets wezen maken). Breidt \RuntimeException rechtstreeks uit, niet NextPdfException.
• Context. Geen getContext(); het is een gewone \RuntimeException. De oorzaak en het betrokken objectnummer worden genoemd in het bericht.
• Herstel. Ontwikkelaarsactie: ontsleutel de bron eerst of lever de sleutel; voor ondertekende bronnen, onderteken in plaats daarvan na het samenvoegen; voor multi-form-merges, flatten of verwijder de formuliervelden van alle bronnen op één na; voor formulier-dragende splits, flatten het formulier vóór het splitsen.

InvalidBcp47TagException

• Wanneer hij wordt opgeworpen. Vanuit Bcp47Validator::validate() wanneer een kandidaat- taaltag misvormd is onder RFC 5646 §2.1 ABNF, of de gecureerde registry-lookup faalt. Domeinspecifiek voor BCP-47 / ISO 14289-2:2024 §8.4.4, te onderscheiden van InvalidConfigException zodat aanroepers stroomafwaarts van de toegankelijkheidsnaad een nauw type kunnen opvangen. Het predicaatpaar Bcp47Validator::isWellFormed() / isValid() blijft het achterwaarts-compatibele return-value-oppervlak voor aanroepers die vertakking boven uitzonderingen verkiezen.
• Context. getContext() geeft tag (de kandidaat exact zoals geleverd) en reason (een stabiele machine-leesbare afwijzingscode, bijv. empty-string, well-formed-shape, unregistered-primary, duplicate-variant) terug. Getypeerde getters: getTag(), getReason().
• Herstel. Ontwikkelaarsactie: corrigeer de taaltag naar een welgevormde, geregistreerde BCP-47-tag. Zie Lettertypen en tagging.

FormFieldAccessibilityException

• Wanneer hij wordt opgeworpen. Wanneer een interactief formulierveld zou steunen op een synthetische (niet door de auteur geleverde) toegankelijke naam terwijl een PDF/UA-document met strikte handhaving van toegankelijke-veldnamen is ingeschakeld wordt geproduceerd. Standaard PDF/UA-uitvoer voert een synthetische fallback-naam in de widget-/Contents zodat een veld nooit naamloos is; strict-modus vereist in plaats daarvan dat de auteur een betekenisvolle naam levert (een tooltip, of een caption voor een actieloze push-button) zodat schermlezergebruikers een echte beschrijving krijgen (ISO 14289-2:2024 §8.10.2).
• Context. Overschrijft getContext() niet, dus geeft hij een lege array terug. De $fieldId is een publieke readonly property; de reden is het bericht.
• Herstel. Ontwikkelaarsactie: lever een tooltip / toegankelijke naam voor het genoemde veld voordat je een strict PDF/UA-document produceert, of schakel strict-modus uit. Zie PDF/A- en PDF/UA-validatie.

VendorExtensionRegistryConflictException

• Wanneer hij wordt opgeworpen. Vanuit VendorExtensionRegistry::register() wanneer een aanroeper een bekende PDF-developer-extension-vendorprefix (ISO 32000-2:2020 §7.12.1) opnieuw registreert met een beschrijving die niet overeenkomt met de reeds-geregistreerde metadata. Descriptors zijn append-only en conflict-gedetecteerd; de getypeerde uitzondering verving een generieke \RuntimeException zodat aanroepers deze specifieke klasse kunnen opvangen.
• Context. getContext() geeft prefix, existing_description en attempted_description terug. Getypeerde getters: getPrefix(), getExistingDescription(), getAttemptedDescription().
• Herstel. Ontwikkelaarsactie: registreer de prefix met de bestaande beschrijving, of gebruik een aparte prefix; overschrijf geregistreerde metadata niet.

Audit-export

AuditExportException

• Wanneer hij wordt opgeworpen. Wanneer de assemblage van een audit-export-bundle, de generatie van een traceability-matrix of de schema-projectie tijdens runtime faalt. Dekt I/O tegen claims.json / manifest.json, JSON-encode/decode van de canonieke bundle, en schema-versie-mismatch op het achterwaarts-compatibele pad AuditExporter::projectToV1(). Het bericht noemt de fase, het artefact indien bekend, en het detail.
• Context. getContext() geeft stage (bijv. read_claims, encode_bundle, project_v1), detail en artefact (pad of schema_version dat de storing veroorzaakte) terug. Getypeerde getters: getStage(), getDetail(), getArtefact().
• Herstel. Compliance-/DevOps-actie: verifieer de invoerartefact-paden, regenereer claims.json vanuit een schone run, of herbouw het manifest voordat je de export opnieuw probeert.

Overtredings-value-objects

Dit zijn geen uitzonderingen. Het zijn onveranderlijke value objects die de engine teruggeeft om een individuele overtreding te beschrijven; zij dragen geen getContext().

ComplianceViolation

• Wat het is. Een final readonly value object dat één regelstoring representeert die wordt gerapporteerd door een externe validator (veraPDF of equivalent), inclusief de ISO- clausuleverwijzing en de locatie binnen de PDF-structuur.
• Velden. Publieke readonly properties: ruleId (validator-regelidentifier, bijv. 6.1.2-1), clause (ISO-clausuleverwijzing, bijv. ISO 19005-1:2005, 6.1.2), severity (bijv. error, warning), location (objectpad binnen de PDF-structuur), en message (voor mensen leesbare beschrijving).
• Gebruik. Inspecteer de collectie die door een compliance-validator wordt teruggegeven; route of toon elke vermelding op severity en clause. Zie PDF/A- en PDF/UA-validatie.

RuleViolation

• Wat het is. Een final readonly value object dat één Schematron- / EN 16931-bedrijfsregelovertreding representeert, teruggegeven door SchematronRunnerInterface::runRules() en geaggregeerd binnen ValidationResult::$ruleViolations. De stabiliteit is experimenteel.
• Velden. Publieke readonly properties: ruleId (EN 16931-identifier zoals BR-{n}, BR-CO-{n}, BR-CL-{n}, BR-DEC-{n}, of een tier-specifiek pakket), severity (een RuleSeverity-enum), message (regeltekst, en-GB), xpath (XPath in de ingebedde XML, null voor document-brede regels), en semanticPath (dot-notatie-BG/BT-pad zoals BG-22.BT-106, null voor structurele overtredingen).
• Gebruik. Inspecteer de collectie op het validatieresultaat; route of toon elke vermelding op severity, ruleId en locator.

Zie ook

• Foutreferentie-index
• Kennisbank-index
• Handtekening- en tijdstempelstoringen
• Versleuteling en machtigingen
• Lettertypen en tagging
• PDF/A- en PDF/UA-validatie