Wissensdatenbank zur Fehlerbehebung

Was diese Wissensdatenbank abdeckt

Diese Wissensdatenbank ordnet beobachtete Fehler den jeweiligen Ursachen und Lösungen zu. Jeder Eintrag ist in den Engine-eigenen Ausnahmeklassen, Fehlerpfad-Tests und Schutzmechanismen im Quellcode verankert — nicht auf Spekulation. Wenn die Engine keinen Codepfad hat, der einen bestimmten Fehler erzeugt, erfindet diese Wissensdatenbank auch keinen.

Die Wissensdatenbank umfasst vier Themenseiten:

• Signaturvalidierung — ungültige Signaturen, unvollständige Ketten, unbekannter Widerrufsstatus und Zeitstempelfehler.
• PDF/A- und PDF/UA-Validierung — fehlender Output Intent, ungetaggter Inhalt, fehlende Sprache und Fehler bei eingebetteten Schriften.
• Schriften und Tagging — nicht gefundene Schriften, Subsetting, CJK-Abdeckung und Probleme mit dem Strukturbaum.
• Verschlüsselung und Berechtigungen — Entschlüsselungsfehler und die Grenze von Berechtigungs-Flags.

So lesen Sie einen Eintrag

Jeder Eintrag hat fünf Teile:

1. Symptom — was Sie beobachten: eine Ausnahmeklasse, ein Nachrichtenfragment oder das Urteil eines nachgelagerten Validators.
2. Wahrscheinliche Ursache — die Bedingung in Ihrer Eingabe oder Konfiguration, die die Engine meldet.
3. Nachweis / Diagnose — wie Sie die Ursache bestätigen. Hier wird die genaue Ausnahmeklasse, das getContext()-Feld oder der Test benannt, der das Verhalten zeigt, damit Sie verifizieren können, statt zu raten.
4. Lösung — die Schritte, mit denen Sie die Ursache beseitigen, als geordnete Prozedur formuliert.
5. Verwandt — die Modul-Referenzseite oder der verwandte Eintrag, den Sie als Nächstes lesen sollten.

Einen Fehler nach Ausnahmetyp identifizieren

NextPDF identifiziert einen Fehler anhand seiner PHP-Klasse, nicht anhand eines String-Fehlercodes. In den Ausnahmeklassen gibt es keine NPDF-####-Konstante. Fangen Sie die Blatt-Ausnahme für eine gezielte Reaktion ab und lesen Sie ContextAwareExceptionInterface::getContext() für strukturierte Diagnosefelder aus. Der Basistyp ist NextPDF\Exception\NextPdfException; Sicherheitsfehler verwenden zusätzlich NextPDF\Security\Exception\SecurityException.

Für die vollständige Hierarchie und die Regeln zur Catch-Reihenfolge lesen Sie die Ausnahmen-Referenz.

<?php

declare(strict_types=1);

use NextPDF\Exception\NextPdfException;
use NextPDF\Contracts\ContextAwareExceptionInterface;

try {
    // ... engine call ...
} catch (NextPdfException $e) {
    $context = $e instanceof ContextAwareExceptionInterface
        ? $e->getContext()
        : [];
    \error_log($e->getMessage());
    // $context carries snake_case primitive fields safe to serialize.
}

Umfang und Abgrenzung

Diese Wissensdatenbank beschreibt die Fehlererkennung und -meldung innerhalb der Engine. Sie beschreibt nicht das Konformitätsurteil eines externen Validators wie veraPDF oder callas; diese Werkzeuge wenden ihre eigenen Regelsätze an. Wo die Engine eine Operation verweigert, um ein Dokument profilkonform zu halten — etwa indem sie Verschlüsselung unter PDF/A verweigert —, nennt der betreffende Eintrag die maßgebliche Klausel und die Ausnahme, die diese Vorgabe durchsetzt.

Siehe auch

• Ausnahmen-Referenz — vollständige Hierarchie, Catch-Reihenfolge, getContext()-Vertrag
• Konformitäts-Referenz — PDF/A-, PDF/UA-, PDF/X-Profilprüfer

Glossar: kontextbewusste Ausnahme