Knowledge base per la risoluzione dei problemi

Cosa contiene questa knowledge base

Questa knowledge base collega gli errori osservati alla causa e alla risoluzione corrispondenti. Ogni voce si fonda sulle classi di eccezione del motore, sui test dei percorsi di errore e sui controlli nel codice sorgente, non su congetture. Se nel motore non esiste un percorso di codice che produce un determinato errore, questa knowledge base non lo inventa.

La knowledge base include quattro pagine tematiche:

• Convalida della firma — firma non valida, catena incompleta, stato di revoca sconosciuto ed errori della marca temporale.
• Convalida PDF/A e PDF/UA — output intent mancante, contenuto privo di tag, lingua mancante, errori nei font incorporati.
• Font e tagging — font non trovato, subsetting, copertura CJK e problemi nell’albero della struttura.
• Cifratura e permessi — errori di decifratura e ambito dei flag dei permessi.

Come leggere una voce

Ogni voce si articola in cinque parti:

1. Sintomo — ciò che si osserva: una classe di eccezione, un frammento di messaggio o il verdetto di un validatore a valle.
2. Causa probabile — la condizione dell’input o della configurazione segnalata dal motore.
3. Evidenza / diagnosi — come accertare la causa. Indica con precisione la classe di eccezione, il campo getContext() o il test che dimostra il comportamento, così da poter verificare invece di procedere per tentativi.
4. Risoluzione — i passaggi per eliminare la causa, descritti come procedura ordinata.
5. Correlati — la pagina di riferimento del modulo o la voce correlata da consultare in seguito.

Identificare un errore dal tipo di eccezione

NextPDF identifica un errore in base alla classe PHP, non tramite un codice di errore espresso come stringa. Nelle classi di eccezione non esiste alcuna costante NPDF-####. Intercettare l’eccezione foglia per ottenere una risposta mirata e leggere ContextAwareExceptionInterface::getContext() per accedere a campi diagnostici strutturati. Il tipo base è NextPDF\Exception\NextPdfException; gli errori di sicurezza usano inoltre NextPDF\Security\Exception\SecurityException.

Per la gerarchia completa e le regole sull’ordine di intercettazione, consultare il riferimento sulle eccezioni.

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

Ambito e confini

Questa knowledge base descrive il rilevamento e la segnalazione degli errori all’interno del motore. Non descrive il verdetto di conformità prodotto da un validatore esterno come veraPDF o callas: questi strumenti applicano insiemi di regole propri. Quando il motore rifiuta un’operazione per mantenere un documento entro un profilo — ad esempio rifiutando la cifratura in PDF/A — la voce pertinente cita la clausola applicabile e l’eccezione che la fa rispettare.

Vedere anche

• Riferimento sulle eccezioni — gerarchia completa, ordine di intercettazione, contratto di getContext()
• Riferimento sulla conformità — verificatori dei profili PDF/A, PDF/UA, PDF/X

Glossario: eccezione context-aware