Runtime- en ondersteuningsfouten

Reikwijdte

Deze vermeldingen documenteren de uitzonderingen die worden opgeworpen door de runtime-ondersteuningslaag: het degradatiebeleid, het cURL-ondersteunde HTTP-transport, de veerkracht- circuit-breaker, de Security Information and Event Management (SIEM)-emitter, het render-manifest, PDF-inspectie en het chaos-engineering-subsysteem.

De meeste NextPDF-uitzonderingen breiden NextPdfException uit, die ContextAwareExceptionInterface implementeert en getContext(): array blootstelt voor gestructureerde diagnostische logging. Een subklasse vult die array alleen wanneer hij getContext() overschrijft; de basis geeft een lege array terug. Drie uitzonderingen op deze pagina (DegradedException, CircuitBreakerOpenException en InspectException) breiden PHP’s RuntimeException rechtstreeks uit en stellen hun data beschikbaar via publieke readonly- properties in plaats van getContext(). Elke vermelding hieronder noemt de exacte properties of contextsleutels die de klasse meedraagt, uit de broncode genomen.

Degradatiebeleid

`DegradedException`

Opgeworpen wanneer. De rendering-pipeline stuit op een gedegradeerde capability die het actieve degradatiebeleid schendt. Onder DegradationPolicy::Strict werpt elke high-impact-degradatie (ComplianceRisk, SemanticLoss of Blocking) hem op; onder DegradationPolicy::Balanced werpt alleen een Blocking-impact hem op.
Klasse. Breidt RuntimeException rechtstreeks uit (niet NextPdfException), dus draagt hij geen getContext().
Meegedragen data. Twee publieke readonly-properties: $capability (het Capability-value-object dat de afwijzing triggerde, inclusief zijn id, status, reason, fallbackTarget en impact) en $policy (het DegradationPolicy dat actief was op het moment van afwijzing). Het bericht heeft de vorm Feature "<id>" is <status>: <reason> (policy: <policy>).
Herstel. Inspecteer $capability om de ontbrekende feature en zijn oorzaak te identificeren. Installeer ofwel de component die de capability vereist, accepteer een configuratie met lagere impact, of versoepel het beleid van Strict naar Balanced wanneer de degradatie acceptabel is voor de use case. Roep $capability->isAvailable() / isDegraded() aan om gebruikersgerichte berichtgeving aan te sturen.

HTTP-transport

Deze drie uitzonderingen ontstaan in de cURL-ondersteunde PSR-18-client en zijn security-aware-decorator. De eerste twee breiden NextPdfException uit maar overschrijven getContext() niet, dus hun getContext() geeft een lege array terug; diagnostische data wordt bereikt via de PSR-18-getRequest()-accessor en de geketende vorige throwable.

`CurlNetworkException`

Opgeworpen wanneer. Het HTTP-verzoek kan niet worden voltooid vanwege een netwerk-niveau-fout: Domain Name System (DNS)-resolutiestoring, connectie-timeout, of Transport Layer Security (TLS)-handshake-fout. Het is ook de klasse die de security-aware-decorator opwerpt voor een security- afwijzing (Server-Side Request Forgery-weigering, DNS-rebinding-weigering, of een geweigerde redirect).
Klasse. Implementeert PSR-18 Psr\Http\Client\NetworkExceptionInterface.
Meegedragen data. getRequest() geeft het gefaalde RequestInterface terug. De oorspronkelijke transportfout, indien aanwezig, is de geketende vorige throwable. getContext() geeft een lege array terug (de basisstandaard).
Herstel. Een netwerkfout kan transiënt zijn — probeer opnieuw met backoff als het verzoek idempotent is. Een security-afwijzing is niet transiënt en moet fail closed gaan: probeer niet opnieuw; corrigeer in plaats daarvan de doel-URL of het SSRF-beleid. Lees het bericht en de vorige throwable om de twee te onderscheiden.

`CurlRequestException`

Opgeworpen wanneer. Het verzoek zelf kan niet worden verzonden omdat het misvormd is, bijvoorbeeld een ongeldige URL of een verzoek dat de SSRF-validatie faalde vóór enige netwerkaanroep.
Klasse. Implementeert PSR-18 Psr\Http\Client\RequestExceptionInterface.
Meegedragen data. getRequest() geeft het overtredende RequestInterface terug; de onderliggende oorzaak, indien aanwezig, is de geketende vorige throwable. getContext() geeft een lege array terug.
Herstel. Dit is een aanroeperinvoer- of beleidsdefect, geen transiënte fout. Probeer niet ongewijzigd opnieuw. Corrigeer de verzoek-URL, headers of body, of pas de SSRF-allowlist aan als het doel legitiem is toegestaan, en geef het verzoek dan opnieuw uit.

`TransientHttpException`

Opgeworpen wanneer. Intern, binnen SecurityAwareHttpClient, om een echt transiënte inner-transport-fout (DNS, connectie of timeout opgeworpen door de inner PSR-18-client) te markeren als in aanmerking komend voor het begrensde retry-budget. Het is de enige retry-eligible klasse die de retry-loop van de decorator herkent; een onverpakte uitzondering (een door de decorator opgeworpen security-afwijzing) wordt behandeld als fataal.
Klasse. Implementeert PSR-18 Psr\Http\Client\NetworkExceptionInterface. Gemarkeerd als @internal — hij wordt volledig binnen SecurityAwareHttpClient aangemaakt en uitgepakt en ontsnapt nooit uit de decorator.
Meegedragen data. getRequest() geeft het gefaalde verzoek terug. De originele inner-transport-ClientExceptionInterface wordt bewaard als de geketende vorige throwable (getPrevious()) en woordelijk opnieuw aan de oppervlakte gebracht naar de aanroeper zodra het retry-budget is uitgeput, zodat het openbare PSR-18-contract ongewijzigd blijft. getContext() geeft een lege array terug.
Herstel. Applicatiecode vangt dit type niet rechtstreeks op. Vang de opnieuw-aan-de-oppervlakte-gebrachte inner-uitzondering op die de decorator teruggeeft nadat het retry- budget is besteed, en behandel herhaalde transiënte storingen als een upstream- beschikbaarheidsprobleem.

Veerkracht

`CircuitBreakerOpenException`

Opgeworpen wanneer. Een CircuitBreaker in de CircuitBreakerState::Open-staat wijst een aanroep fail-fast af, vóór enige downstream-invocatie. Hij bestaat om aanroepers “de remote service is nu onbereikbaar” te laten onderscheiden (een transiënte transportfout, het degraderen waard) van “de connection pool zou door deze aanroep zijn uitgeput” (fail-fast, geen netwerk geprobeerd) — de batch denial-of-service-mitigatie vereist voor Public Key Infrastructure (PKI)-clients.
Klasse. Breidt RuntimeException rechtstreeks uit, dus draagt hij geen getContext().
Meegedragen data. Twee publieke readonly-properties: $breakerName (de identifier van de open breaker) en $secondsUntilHalfOpen (de bij benadering resterende cooldown voordat de breaker overgaat naar half-open). Het bericht heeft de vorm Circuit breaker "<name>" is OPEN (cooldown ~<n>s remaining); call rejected fail-fast.
Herstel. Beuk niet op de breaker — wacht minstens $secondsUntilHalfOpen voordat je opnieuw probeert, of degradeer de bewerking. Geen netwerkaanroep werd geprobeerd, dus dit is geen bewijs dat de remote service zelf faalde; het is back-pressure die de connection pool beschermt.

Observeerbaarheid

`SiemEmitterException`

Opgeworpen wanneer. Een SIEM-event-emitter kan een record niet persisteren of ketenen. Hij brengt filesystem-niveau-storingen (open, lock, seek, write, fflush, read) en hash-chain-integriteitsfouten (chain: out-of-order- index, misvormd tail-record, of JSON-round-trip-drift) aan de oppervlakte, gedeeld over de hash-chain-event-log en de JSON-lines-file-emitter-adapters.
Klasse. Breidt NextPdfException uit en overschrijft getContext().
Contextsleutels. operation (een van open, lock, seek, write, fflush, read, chain), path (het doel-logpad) en detail (een voor mensen leesbaar detail zoals byte-aantallen of verwachte-versus-werkelijke index). Deze zijn ook bereikbaar via getOperation(), getPath() en getDetail(). Het bericht heeft de vorm SIEM emitter <operation> failed for <path>: <detail>.
Herstel. Dit is actiegericht door infrastructuur of SecOps, niet door applicatielogica. Verifieer de log-volume-mount, directory-machtigingen, beschikbare file descriptors en filesystem-gezondheid. Een chain-bewerkings- storing duidt op een manipulatie- of corruptiesignaal in het audit-log en moet worden onderzocht, niet stilletjes opnieuw geprobeerd.

Render-manifest

`RenderManifestException`

Opgeworpen wanneer. Een RenderManifest kan niet worden geconstrueerd, gedeserialiseerd of gelezen vanwege een structurele, type- of schema-compatibiliteitsfout. Het manifest is een geversioneerd openbaar contract dat door elk transport wordt ingediend (CLI, Laravel-queue, Symfony, de SaaS-API), dus een misvormd of incompatibel manifest wordt rechtstreeks aan de oppervlakte gebracht in plaats van naar standaarden gecoerceerd.
Klasse. Breidt NextPdfException uit en overschrijft getContext(). Benoemde constructors stellen een stabiele machine-leesbare code in de SPEC-MANIFEST-*- namespace in:
- RenderManifestException::shape() → SPEC-MANIFEST-001 — vorm- of type- fout tijdens RenderManifest::fromArray().
- RenderManifestException::incompatibleVersion() → SPEC-MANIFEST-002 — incompatibele major-schema-versie (kan niet worden gelezen).
- RenderManifestException::missingField() → SPEC-MANIFEST-003 — vereist veld ontbreekt tijdens builder-finalisatie.
- RenderManifestException::unsupported() → SPEC-MANIFEST-004 — een welgevormd manifest verwijst naar een invoer of template die de huidige renderer niet kan resolven (bijvoorbeeld een URI-invoer of een host-only template-engine).
Contextsleutels. manifest_code (de SPEC-MANIFEST-*-identifier) en reason (de voor mensen leesbare storingsbeschrijving). Deze zijn ook bereikbaar via getManifestCode() en getReason(). Het bericht heeft de vorm [<code>] <reason>.
Herstel. Vertak op manifest_code. Voor SPEC-MANIFEST-001 en SPEC-MANIFEST-003, corrigeer de manifest-payload (corrigeer het veldtype of lever het ontbrekende veld). Voor SPEC-MANIFEST-002, regenereer het manifest tegen een ondersteunde major-schema-versie of upgrade de renderer. Voor SPEC-MANIFEST-004, lever een invoer of template-engine die de huidige editie kan resolven.

Inspectie

`InspectException`

Opgeworpen wanneer. PDF-inspectie faalt.
Klasse. Breidt RuntimeException rechtstreeks uit (niet NextPdfException), dus draagt hij geen getContext().
Meegedragen data. Twee publieke readonly-properties: $inspectCode (een machine-leesbare code in de INSPECT-*-namespace) en $retryable (een boolean die aangeeft of de aanroeper opnieuw zou moeten proberen — bijvoorbeeld wanneer een inspectie-sidecar tijdelijk down is). De oorspronkelijke oorzaak, indien aanwezig, is de geketende vorige throwable.
Herstel. Vertak op $inspectCode voor de specifieke storingsklasse. Wanneer $retryable true is, probeer opnieuw met backoff omdat de storing naar verwachting transiënt is (zoals een sidecar-herstart); wanneer false, behandel de invoer of configuratie als het defect en probeer niet ongewijzigd opnieuw.

Chaos-engineering

`ChaosReportWriteException`

Opgeworpen wanneer. ChaosScenarioRunner::writeReport() kan het geaggregeerde chaos-day-rapport niet naar schijf persisteren. Het is een domein-getypeerde vervanging voor een generieke runtime-fout, zodat aanroepers de specifieke report-disk-storing kunnen opvangen zonder hem te verwarren met fouten die binnen de scenario-simulators zelf worden opgeworpen (de runner legt die vast als ChaosOutcome-velden).
Klasse. Breidt NextPdfException uit en overschrijft getContext().
Contextsleutels. output_path (het absolute pad dat de runner probeerde te schrijven). Het is ook bereikbaar via getOutputPath(). Het bericht heeft de vorm ChaosScenarioRunner: failed to write report to "<path>".
Herstel. Dit is een schrijfzijde-storing van de report-sink, niet van de scenario’s. Verifieer dat de uitvoerdirectory bestaat en schrijfbaar is en dat schijf- ruimte beschikbaar is, en voer dan de report-write opnieuw uit. De chaos-uitkomsten zelf zijn onaangetast.

`RetrievalUnavailableException`

Opgeworpen wanneer. Een retrieval-endpoint (bijvoorbeeld een Voyage Retrieval Augmented Generation-service) is niet beschikbaar en het systeem valt ofwel terug op cached-only-modus of gaat fail-closed.
Klasse. Breidt NextPdfException uit en overschrijft getContext().
Contextsleutels. mode (de operationele modus na de storing — CACHED_ONLY wanneer resultaten alleen vanuit de semantische cache worden geserveerd, of FAIL_CLOSED wanneer het verzoek volledig wordt geweigerd zonder verouderde data) en endpoint (het endpoint dat onbereikbaar werd). Deze zijn ook bereikbaar via getMode() en getEndpoint(). Het bericht heeft de vorm Retrieval endpoint "<endpoint>" is unavailable; operating in <mode> mode.
Herstel. Lees mode om te leren hoe het systeem degradeerde. Onder CACHED_ONLY kunnen resultaten verouderd zijn; ververs zodra het endpoint herstelt. Onder FAIL_CLOSED werd het verzoek by design geweigerd en moet het opnieuw worden geprobeerd nadat het endpoint bereikbaar is. Herstel de endpoint-connectiviteit (netwerk, credentials, service-gezondheid) voordat je afhankelijk bent van verse retrieval.

Runtime- en ondersteuningsfouten

Reikwijdte

Degradatiebeleid

DegradedException

HTTP-transport

CurlNetworkException

CurlRequestException

TransientHttpException

Veerkracht

CircuitBreakerOpenException