Fehlerreferenz

Dies ist die Referenzliste der Exceptions, die NextPDF Core auslöst, nach Bereich geordnet. Jede Kategorieseite dokumentiert pro Klasse, wann sie ausgelöst wird, welche strukturierten Daten sie trägt und wie Sie sich davon erholen. Wenn Sie ein Symptom diagnostizieren statt eine bestimmte Klasse abzufangen, beginnen Sie stattdessen mit den Leitfäden zur Fehlerbehebung — sie sind danach geordnet, was Sie beobachten.

Auf einen Blick

• Die meisten Exceptions erweitern eine einzige Basis, NextPdfException, sodass Sie die gesamte Familie mit einem einzigen catch-Block abfangen können.
• NextPdfException ist kontextbewusst: Es implementiert ContextAwareExceptionInterface, das getContext(): array deklariert. Viele Unterklassen überschreiben getContext(), um strukturierte Diagnoseschlüssel zurückzugeben; andere erben die leere Voreinstellung und legen ihr Detail über die Meldung und typisierte Getter offen.
• Eine kleine Zahl von Low-Level-Exceptions erweitert direkt PHPs \RuntimeException statt NextPdfException. Diese sind nicht kontextbewusst und tragen ihr Detail auf öffentlichen readonly-Eigenschaften. Jede Kategorieseite kennzeichnet sie ausdrücklich.
• Zwei Compliance-Typen mit dem Namen …Violation (ComplianceViolation, RuleViolation) sind Value Objects, keine Exceptions — sie beschreiben einen Befund, ohne ausgelöst zu werden.

Der Basistyp und der Kontextvertrag

NextPdfException ist eine abstrakte Klasse, die \RuntimeException erweitert und ContextAwareExceptionInterface implementiert. Der Vertrag ist klein:

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

Ein defensiver Handler sieht daher so aus:

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.
}

Da einige Fehler als nackte \RuntimeException auftreten (siehe die kategoriespezifischen Hinweise), kann eine doppelt abgesicherte Grenze auch \RuntimeException abfangen und den konkreten Typ untersuchen.

Kategorien

• Core- und allgemeine Fehler — Fehler bei Dokument, Zusammenführung, Barrierefreiheit, E-Rechnung, Farbraum, Value Object und Strict-Modus sowie die gemeinsamen Basistypen.
• Security-, Signier- und PKI-Fehler — Signaturerstellung und -prüfung, Zeitstempel, PKI-Pfad- und Namensbeschränkungsvalidierung, Hashing, Integrität und PKCS#11.
• Rendering- und I/O-Fehler — HTML-Layout und Paged Media, Schriften und Text-Shaping, der Writer und Reader sowie XMP-Metadaten.
• Laufzeit- und Support-Fehler — HTTP-Transport, Resilienz (Circuit Breaker, Degraded-Modus), Observability und Manifest-Handhabung.
• Accelerator-Fehler — der optionale Beschleunigungs-Sidecar-Transport.
• Compliance-Fehler — Anforderungen an Klausel-Hashes und der Compliance-Lebenszyklus.

Siehe auch

• Fehlerbehebung — symptomorientierte Leitfäden zu Signaturvalidierung, Verschlüsselung und Berechtigungen, Schriften und Tagging und PDF/A- und PDF/UA-Validierung.