Exception: typisierte Ausnahmehierarchie

Auf einen Blick

Jede Ausnahme, die NextPDF wirft, leitet sich von einer einzigen abstrakten Basisklasse ab: NextPdfException. Dadurch fängt ein einziger catch jeden Engine-Fehler ab. Jede Domänenausnahme implementiert ContextAwareExceptionInterface und stellt strukturierte Diagnosefelder für Logging und APM bereit, ohne dass Sie den Nachrichtentext parsen müssen.

Installation

composer require nextpdf/core:^3

Konzeptioneller Überblick

Die Hierarchie hat drei Ebenen:

RuntimeException (PHP SPL)
  └── NextPdfException (abstract; implements ContextAwareExceptionInterface)
        ├── InvalidConfigException
        ├── FontNotFoundException
        ├── FontParsingException
        ├── ImageProcessingException
        ├── SignatureException
        ├── EncryptionException
        ├── WriterException
        ├── PageLayoutException
        ├── HtmlParsingException
        ├── CompressionException
        ├── NotImplementedException
        ├── … (23 domain exceptions total)
        └── Strict\StrictModeViolation (abstract)
              ├── Strict\IncompatibleRenderingModeException
              ├── Strict\OracleConformanceFailure
              └── Strict\UnregisteredCssDeviation

NextPdfException erweitert die SPL-Klasse RuntimeException. Wenn Sie RuntimeException abfangen, fangen Sie auch NextPDF-Fehler ab. Wenn Sie NextPdfException abfangen, beschränken Sie sich auf Engine-Fehler. Fangen Sie eine Blattklasse ab, um gezielt zu reagieren. Der Strict\-Teilbaum gruppiert Verletzungen des Konformitätsmodus unter der abstrakten StrictModeViolation, die ihrerseits NextPdfException erweitert.

Kontext statt Zeichenketten-Codes. NextPDF identifiziert einen Fehler über seinen PHP-Typ, nicht über einen Fehlercode als Zeichenkette. In den Ausnahmeklassen gibt es keine NPDF-####-Code-Konstante. Stattdessen liefert ContextAwareExceptionInterface::getContext() ein array<string, mixed> mit primitiven Feldern im snake_case-Format, die sich gefahrlos in eine Log- oder APM-Nutzlast serialisieren lassen. NextPdfException::getContext() liefert standardmäßig []. Jede Domänenausnahme überschreibt diese Methode mit den Feldern, die für diesen Fehler relevant sind. FontNotFoundException::getContext() liefert zum Beispiel font_name, search_paths und fallback_attempted. WriterException liefert output_path und writer_state. InvalidConfigException liefert config_key, given_value und expected_type. Die separaten, stabilen Zeichenketten-Bezeichner NEXTPDF_W_* gehören zum nicht-fatalen WarningCode-Enum im Support-Modul, nicht zu den Ausnahmen.

Handlungsfähigkeit. Der Klassen-Docblock jeder Domänenausnahme nennt, wer sinnvoll darauf reagieren kann — Entwickler, Infrastruktur oder aufrufende Bibliothek. InvalidConfigException ist ein Entwicklerfehler (korrigieren Sie die Konfiguration). FontNotFoundException ist ein Entwickler- oder Infrastrukturfehler (prüfen Sie den Pfad oder die Dateiberechtigungen). WriterException ist ein Infrastrukturfehler (Festplatte, Berechtigungen, Ausgabestream). NotImplementedException ist ein Aufruferfehler (entfernen Sie den Aufruf oder pinnen Sie die Version auf ein Release, das die genannte Folgearbeit liefert). Mehrere Ausnahmen stellen benannte Konstruktoren für präzise Grundursachen bereit — SignatureException::ltvCapabilityMissing(), ::tsaRequired() und ähnliche —, damit Betreiber die tatsächliche Ursache sehen statt einer generischen Meldung.

API-Oberfläche

Symbol	Art	Wichtige Member
NextPDF\Contracts\ContextAwareExceptionInterface	interface	getContext(): array<string, mixed>
NextPDF\Exception\NextPdfException	abstract class	erweitert RuntimeException; getContext() (Standard [])
NextPDF\Exception\InvalidConfigException	final	getConfigKey(), getGivenValue(), getExpectedType(), getContext()
NextPDF\Exception\FontNotFoundException	final	getFontName(), getSearchPaths(), wasFallbackAttempted(), getContext()
NextPDF\Exception\SignatureException	final	getCertInfo(), getSignatureLevel(), getDetail(), getContext(); benannte Konstruktoren ltvCapabilityMissing(), tsaRequired(), httpClientMissing(), …
NextPDF\Exception\WriterException	final	getOutputPath(), getWriterState(), getContext()
NextPDF\Exception\PageLayoutException	final	getPageNumber(), getContext()
NextPDF\Exception\NotImplementedException	final	$feature, $followUp
NextPDF\Exception\Strict\StrictModeViolation	abstract	erweitert NextPdfException
NextPDF\Exception\Strict\IncompatibleRenderingModeException	final	erweitert StrictModeViolation

Vollständige Menge der Blattklassen (23): BarcodeEncoderNotFoundException, BarcodeException, CompressionException, ContentStreamBalanceException, CssParserLimitExceededException, CssResolutionBudgetExceededException, EncryptionException, FontNotFoundException, FontParsingException, GraphicsStateBalanceException, HtmlParsingException, ImageProcessingException, InvalidConfigException, LinearizationInvariantException, LinearizationUnimplementedException, MissingShadingResourceException, NotImplementedException, PageLayoutException, PdfRViolationException, SignatureException, TemplateException, UnsupportedAlgorithmException, WriterException.

Codebeispiel — Schnellstart

Fangen Sie jeden Engine-Fehler über den Basistyp ab.

<?php

declare(strict_types=1);

use NextPDF\Core\Document;
use NextPDF\Exception\NextPdfException;

try {
    $doc = Document::createStandalone();
    $doc->addPage();
    $doc->setFont('helvetica', '', 12);
    $doc->cell(0, 10, 'Hello');
    $doc->save('out.pdf');
} catch (NextPdfException $e) {
    \error_log($e->getMessage());
}

examples/15-exception-handling.php zeigt dieses Muster vollständig.

Codebeispiel — Produktion

Reagieren Sie auf Blattebene und leiten Sie strukturierten Kontext an die Log-Pipeline weiter.

<?php

declare(strict_types=1);

use NextPDF\Contracts\ContextAwareExceptionInterface;
use NextPDF\Core\Document;
use NextPDF\Exception\FontNotFoundException;
use NextPDF\Exception\NextPdfException;
use Psr\Log\LoggerInterface;

function render(Document $doc, LoggerInterface $logger): void
{
    try {
        $doc->setFont('Brand-Sans', '', 12);
        $doc->cell(0, 10, 'Invoice');
        $doc->save('invoice.pdf');
    } catch (FontNotFoundException $e) {
        // Targeted recovery: fall back to a built-in font.
        $logger->warning($e->getMessage(), $e->getContext());
        $doc->setFont('helvetica', '', 12);
        $doc->save('invoice.pdf');
    } catch (NextPdfException $e) {
        // Any other engine error: structured context, then rethrow.
        $context = $e instanceof ContextAwareExceptionInterface
            ? $e->getContext()
            : [];
        $logger->error($e->getMessage(), $context);
        throw $e;
    }
}

Randfälle & Fallstricke

• Die Reihenfolge der Catch-Blöcke ist wichtig. Listen Sie Blattklassen vor NextPdfException auf. Ein vorangestelltes catch (NextPdfException) schluckt jede Unterklasse.
• getContext()-Schlüssel sind im snake_case-Format und die Werte sind Primitive oder Listen von Primitiven — keine verschachtelten Objekte —, sodass die Nutzlast immer JSON-sicher ist.
• Die Basis-NextPdfException::getContext() liefert []. Eine Unterklasse, die diese Methode nicht überschreibt, trägt keine strukturierten Felder. Verlassen Sie sich dort auf getMessage().
• NextPdfException ist abstrakt — Sie können sie nicht direkt instanziieren. Werfen Sie eine konkrete Blattklasse.
• NotImplementedException ist absichtlich laut: sie signalisiert eine bewusst fehlende Implementierung, keinen vorübergehenden Fehler. Versuchen Sie den Vorgang nicht einfach erneut.
• Strict\*-Verletzungen weisen auf einen Vertragsbruch im Konformitätsmodus hin, nicht auf einen behebbaren Laufzeitfehler. Behandeln Sie sie als Konfigurations- oder Eingabefehler.
• Es gibt keine Fehlercode-Konstante als Zeichenkette. Gleichen Sie anhand des Ausnahmetyps ab. Leiten Sie getContext() für maschinelle Konsumenten weiter.

Performance

Das Konstruieren einer Ausnahme besteht aus einer einzigen Objektzuweisung und dem sprintf, das die Meldung aufbaut — O(1). getContext() liefert ein kleines assoziatives Array, das aus bereits gespeicherten Feldern aufgebaut wird, O(1) in der Anzahl der Felder. Ausnahmen liegen auf dem Fehlerpfad, nicht auf dem Hot Path. Die Kosten sind im Vergleich zur fehlgeschlagenen Arbeit vernachlässigbar. Das standardmäßige performance_budget für diese Referenzseite ist wall_ms: 1500, peak_mb: 64.

Sicherheitshinweise

Kontextfelder können aus dem Dokument abgeleitete Details enthalten: FontNotFoundException enthält Suchpfade im Dateisystem, WriterException enthält den Ausgabepfad, InvalidConfigException enthält den übergebenen Wert. Bereinigen Sie die Kontextschlüssel oder lassen Sie nur ausdrücklich erlaubte Schlüssel zu, bevor Sie sie an eine wenig vertrauenswürdige Log-Senke weiterleiten, da Pfade und Werte das Deployment-Layout oder Benutzereingaben preisgeben können. Ausnahmemeldungen sind menschenlesbar und können dasselbe Detail enthalten — geben Sie in einem sicherheitskritischen Kontext keine unverarbeiteten Meldungen an Endbenutzer aus. SignatureException bindet die konkrete Grundursache (fehlendes Paket, leere TSA-URL) bewusst an die Meldung, damit Betreiber triagieren können, ohne Aufrufstellen durchsuchen zu müssen. Dieses Detail richtet sich an Betreiber, nicht an Endbenutzer.

Konformität

Dieses Modul beschreibt das Fehlermodell der Engine und enthält keine normative Standardangabe. Ausnahmen, die wegen Standardverletzungen ausgelöst werden — zum Beispiel PdfRViolationException oder Strict\OracleConformanceFailure — verweisen im Modul, das die Verletzung erkennt, auf ihre maßgebliche Klausel, nicht hier.

Siehe auch

• /modules/core/contracts/ — Definition von ContextAwareExceptionInterface
• /modules/core/observability/ — Weiterleitung von getContext() an APM
• /modules/core/config/ — InvalidConfigException, NotImplementedException
• /modules/core/support/ — DegradedException; WarningCode (NEXTPDF_W_*)
• /modules/core/event/ — InvalidConfigException aus addListener()

Glossar: kontextbewusste Ausnahme · Degradationsrichtlinie