Exception: getypeerde exceptiehiërarchie

In één oogopslag

Elke exceptie die NextPDF opwerpt, is afgeleid van één abstracte basisklasse, NextPdfException, zodat je elke enginefout met één catch kunt afhandelen. Elke domeinexceptie implementeert ContextAwareExceptionInterface en stelt gestructureerde diagnostische velden beschikbaar voor logging en application performance monitoring (APM), zonder dat je de berichttekst hoeft te parsen.

Installatie

composer require nextpdf/core:^3

Conceptueel overzicht

De hiërarchie kent drie lagen:

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 is afgeleid van RuntimeException uit de Standard PHP Library (SPL). Als je RuntimeException afvangt, vang je ook NextPDF-fouten af. Met NextPdfException beperk je de handler tot enginefouten. Vang een leaf-klasse af voor gericht herstel. De subboom Strict\ groepeert schendingen van de conformiteitsmodus onder de abstracte StrictModeViolation, die zelf van NextPdfException is afgeleid.

Context, geen stringcodes. NextPDF identificeert een fout op basis van het PHP-type, niet aan de hand van een foutcode in stringvorm. De exceptieklassen definiëren geen NPDF-####-codeconstante. In plaats daarvan retourneert ContextAwareExceptionInterface::getContext() een array<string, mixed> met primitieve velden in snake_case die veilig naar een log- of APM-payload kunnen worden geserialiseerd. NextPdfException::getContext() retourneert standaard []. Elke domeinexceptie overschrijft dit met velden die specifiek zijn voor die fout. Zo retourneert FontNotFoundException::getContext() de velden font_name, search_paths en fallback_attempted. WriterException retourneert output_path en writer_state. InvalidConfigException retourneert config_key, given_value en expected_type. De stabiele stringidentifiers NEXTPDF_W_* horen bij de niet-fatale enum WarningCode in de Support-module, niet bij excepties.

Afhandelbaarheid. De class-docblock van elke domeinexceptie vermeldt wie er actie op kan ondernemen: de ontwikkelaar, de infrastructuur of de aanroeper van de library. InvalidConfigException is een ontwikkelaarsfout; corrigeer de configuratie. FontNotFoundException is een ontwikkelaars- of infrastructuurfout; controleer het pad of de bestandsrechten. WriterException is een infrastructuurfout; controleer de schijf, de rechten of de outputstream. NotImplementedException is een aanroeperfout; verwijder de aanroep of pin op een release die de genoemde follow-up bevat. Verschillende excepties bieden named constructors voor nauwkeurige grondoorzaken: SignatureException::ltvCapabilityMissing(), ::tsaRequired() en dergelijke. Operators zien de werkelijke oorzaak in plaats van een algemeen bericht.

API-oppervlak

Symbool	Soort	Belangrijkste members
NextPDF\Contracts\ContextAwareExceptionInterface	interface	getContext(): array<string, mixed>
NextPDF\Exception\NextPdfException	abstract class	is afgeleid van RuntimeException; getContext() (standaard [])
NextPDF\Exception\InvalidConfigException	final	getConfigKey(), getGivenValue(), getExpectedType(), getContext()
NextPDF\Exception\FontNotFoundException	final	getFontName(), getSearchPaths(), wasFallbackAttempted(), getContext()
NextPDF\Exception\SignatureException	final	getCertInfo(), getSignatureLevel(), getDetail(), getContext(); named constructors 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	is afgeleid van NextPdfException
NextPDF\Exception\Strict\IncompatibleRenderingModeException	final	is afgeleid van StrictModeViolation

Volledige set leaf-klassen (23): BarcodeEncoderNotFoundException, BarcodeException, CompressionException, ContentStreamBalanceException, CssParserLimitExceededException, CssResolutionBudgetExceededException, EncryptionException, FontNotFoundException, FontParsingException, GraphicsStateBalanceException, HtmlParsingException, ImageProcessingException, InvalidConfigException, LinearizationInvariantException, LinearizationUnimplementedException, MissingShadingResourceException, NotImplementedException, PageLayoutException, PdfRViolationException, SignatureException, TemplateException, UnsupportedAlgorithmException, WriterException.

Codevoorbeeld — snelle start

Vang elke enginefout af via het basistype.

<?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());
}

Het uitvoerbare voorbeeld examples/15-exception-handling.php demonstreert dit patroon.

Codevoorbeeld — productie

Herstel op leaf-niveau en stuur gestructureerde context naar de logpijplijn.

<?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;
    }
}

Randgevallen en valkuilen

• De volgorde van catch-blokken is belangrijk. Zet leaf-klassen vóór NextPdfException; een eerdere catch (NextPdfException) vangt elke subklasse af.
• De sleutels van getContext() gebruiken snake_case. De waarden zijn primitieven of lijsten van primitieven, zonder geneste objecten. De payload is veilig te serialiseren naar JavaScript Object Notation (JSON).
• De basis NextPdfException::getContext() retourneert []. Een subklasse die dit niet overschrijft, bevat geen gestructureerde velden. Vertrouw in dat geval op getMessage().
• NextPdfException is abstract; je kunt deze niet rechtstreeks instantiëren. Werp een concrete leaf-klasse op.
• NotImplementedException is bewust expliciet. De exceptie signaleert een opzettelijk ontbrekende implementatie, geen tijdelijke fout. Probeer de aanroep niet opnieuw.
• Strict\*-schendingen duiden op een contractbreuk in de conformiteitsmodus, niet op een herstelbare runtimefout. Behandel ze als configuratie- of invoerdefecten.
• Er bestaat geen foutcodeconstante in stringvorm. Match op het exceptietype. Stuur getContext() door voor machineconsumenten.

Prestaties

Het construeren van een exceptie veroorzaakt één objectallocatie plus de sprintf-aanroep waarmee het bericht wordt opgebouwd: O(1). getContext() retourneert een kleine associatieve array die uit al aanwezige velden wordt opgebouwd: O(1) in het aantal velden. Excepties worden gebruikt op het foutpad, niet op het hot path. De kosten zijn verwaarloosbaar vergeleken met het werk dat is mislukt. Het standaard performance_budget voor deze referentiepagina is wall_ms: 1500, peak_mb: 64.

Beveiligingsnotities

Contextvelden kunnen details bevatten die uit het document komen. FontNotFoundException bevat zoekpaden in het bestandssysteem, WriterException bevat het outputpad en InvalidConfigException bevat de opgegeven waarde. Voordat je context doorstuurt naar een minder vertrouwde logbestemming, schoon je velden op of geef je alleen een allowlist van sleutels door, omdat paden en waarden de deploymentstructuur of gebruikersinvoer kunnen prijsgeven. Exceptieberichten zijn leesbaar voor mensen en kunnen dezelfde details bevatten. Toon ruwe berichten niet aan eindgebruikers in een beveiligingsgevoelige context. SignatureException koppelt bewust de concrete grondoorzaak, zoals een ontbrekend pakket of een lege Uniform Resource Locator (URL) voor een Time Stamping Authority (TSA), aan het bericht, zodat operators kunnen triageren zonder de aanroeplocaties te doorzoeken. Die details zijn bedoeld voor operators, niet voor eindgebruikers.

Conformiteit

Deze module definieert een engine-foutmodel en bevat geen normatieve standaardverwijzing. Excepties die worden opgeworpen bij standaardschendingen, bijvoorbeeld PdfRViolationException of Strict\OracleConformanceFailure, verwijzen naar hun maatgevende clausule in de module die de schending detecteert, niet hier.

Zie ook

• /modules/core/contracts/ — definitie van ContextAwareExceptionInterface
• /modules/core/observability/ — getContext() doorsturen naar APM
• /modules/core/config/ — InvalidConfigException, NotImplementedException
• /modules/core/support/ — DegradedException; WarningCode (NEXTPDF_W_*)
• /modules/core/event/ — InvalidConfigException vanuit addListener()

Woordenlijst: context-bewuste exceptie · degradatiebeleid