Foutreferentie

Dit is de referentielijst van de uitzonderingen die NextPDF Core opwerpt, geordend per gebied. Elke categoriepagina documenteert per klasse wanneer hij wordt opgeworpen, welke gestructureerde data hij meedraagt en hoe je ervan herstelt. Diagnostiseer je een symptoom in plaats van dat je een specifieke klasse opvangt, begin dan in plaats daarvan met de gidsen voor probleemoplossing — die zijn geordend naar wat je waarneemt.

In een oogopslag

• De meeste uitzonderingen breiden één enkele basis uit, NextPdfException, zodat je de hele familie met één catch-blok kunt opvangen.
• NextPdfException is context-bewust: hij implementeert ContextAwareExceptionInterface, die getContext(): array declareert. Veel subklassen overschrijven getContext() om gestructureerde diagnostische sleutels terug te geven; andere erven de lege standaard en stellen hun detail beschikbaar via het bericht en getypeerde getters.
• Een klein aantal laag-niveau-uitzonderingen breidt PHP’s \RuntimeException rechtstreeks uit in plaats van NextPdfException. Deze zijn niet context-bewust en dragen hun detail op publieke readonly properties. Elke categoriepagina markeert ze expliciet.
• Twee compliance-types met de naam …Violation (ComplianceViolation, RuleViolation) zijn value objects, geen uitzonderingen — zij beschrijven een bevinding zonder te worden opgeworpen.

Het basistype en het context-contract

NextPdfException is een abstracte klasse die \RuntimeException uitbreidt en ContextAwareExceptionInterface implementeert. Het contract is klein:

interface ContextAwareExceptionInterface
{
    /** @return array<string, mixed> structured, log-safe diagnostic context */
    public function getContext(): array;
}

Een defensieve handler ziet er daarom zo uit:

use NextPDF\Exception\NextPdfException;

try {
    // … NextPDF operation …
} catch (NextPdfException $e) {
    $logger->error($e->getMessage(), $e->getContext());
    // getContext() returns [] when a subclass does not override it;
    // the message and any typed getters still carry the detail.
}

Omdat sommige storingen als een kale \RuntimeException aan de oppervlakte komen (zie de notities per categorie), kan een dubbel-beveiligde grens ook \RuntimeException opvangen en het concrete type inspecteren.

Categorieën

• Core- en algemene fouten — storingen rond documenten, samenvoegen, toegankelijkheid, e-facturen, kleurruimte, value objects en strict-modus, plus de gedeelde basistypes.
• Beveiligings-, ondertekenings- en PKI-fouten — handtekeningcreatie en -verificatie, tijdstempels, PKI-padvalidatie en validatie van naambeperkingen, hashing, integriteit en PKCS#11.
• Rendering- en I/O-fouten — HTML-lay-out en paged media, lettertypen en tekstshaping, de writer en reader, en XMP-metadata.
• Runtime- en ondersteuningsfouten — HTTP-transport, veerkracht (circuit breaker, gedegradeerde modus), observeerbaarheid en manifestafhandeling.
• Accelerator-fouten — het transport van de optionele acceleratie-sidecar.
• Compliance-fouten — clause-hash-vereisten en de compliance-levenscyclus.

Zie ook

• Probleemoplossing — op symptomen geordende gidsen voor handtekeningvalidatie, versleuteling en machtigingen, lettertypen en tagging, en PDF/A- en PDF/UA-validatie.