Referencia de errores

Esta es la lista de referencia de las excepciones que lanza NextPDF Core, organizada por área. Cada página de categoría documenta, por clase, cuándo se lanza, los datos estructurados que transporta y cómo recuperarse. Si se está diagnosticando un síntoma en lugar de capturar una clase concreta, conviene empezar por las guías de resolución de problemas: están organizadas según lo que se observa.

De un vistazo

• La mayoría de las excepciones extienden una única base, NextPdfException, de modo que se puede capturar toda la familia con un solo bloque catch.
• NextPdfException es consciente del contexto: implementa ContextAwareExceptionInterface, que declara getContext(): array. Muchas subclases redefinen getContext() para devolver claves de diagnóstico estructuradas; otras heredan el valor predeterminado vacío y exponen su detalle a través del mensaje y de captadores tipados.
• Un número reducido de excepciones de bajo nivel extiende directamente \RuntimeException de PHP en lugar de NextPdfException. Estas no son conscientes del contexto y transportan su detalle en propiedades públicas de solo lectura. Cada página de categoría las señala explícitamente.
• Dos tipos de conformidad llamados …Violation (ComplianceViolation, RuleViolation) son objetos de valor, no excepciones: describen un hallazgo sin ser lanzados.

El tipo base y el contrato de contexto

NextPdfException es una clase abstracta que extiende \RuntimeException e implementa ContextAwareExceptionInterface. El contrato es reducido:

interface ContextAwareExceptionInterface
{
    /** @return array<string, mixed> structured, log-safe diagnostic context */
    public function getContext(): array;
}

Por tanto, un manejador defensivo tiene este aspecto:

use NextPDF\Exception\NextPdfException;

try {
    // … NextPDF operation …
} catch (NextPdfException $e) {
    $logger->error($e->getMessage(), $e->getContext());
    // getContext() returns [] when a subclass does not override it;
    // the message and any typed getters still carry the detail.
}

Dado que algunos fallos afloran como una \RuntimeException simple (véanse las notas por categoría), un límite con doble protección puede además capturar \RuntimeException e inspeccionar el tipo concreto.

Categorías

• Errores del núcleo y generales — fallos de documento, fusión, accesibilidad, factura electrónica, espacio de color, objetos de valor y modo estricto, además de los tipos base compartidos.
• Errores de seguridad, firma y PKI — creación y verificación de firmas, marcas de tiempo, validación de rutas PKI y restricciones de nombre, hashing, integridad y PKCS#11.
• Errores de representación y de E/S — maquetación HTML y soportes paginados, fuentes y conformado de texto, el escritor y el lector, y los metadatos XMP.
• Errores de tiempo de ejecución y de soporte — transporte HTTP, resiliencia (disyuntor, modo degradado), observabilidad y manejo del manifiesto.
• Errores del acelerador — el transporte del sidecar de aceleración opcional.
• Errores de conformidad — requisitos de hash de cláusula y el ciclo de vida de conformidad.

Véase también

• Resolución de problemas — guías organizadas por síntoma para la validación de firmas, el cifrado y los permisos, las fuentes y el etiquetado, y la validación de PDF/A y PDF/UA.