Exception: jerarquía tipada de excepciones

De un vistazo

Todas las excepciones que lanza NextPDF extienden una única base abstracta, NextPdfException, lo que permite que un solo catch gestione cualquier error del motor. Cada excepción de dominio implementa ContextAwareExceptionInterface y expone campos de diagnóstico estructurados para el registro y el APM, sin analizar la cadena del mensaje.

Instalación

composer require nextpdf/core:^3

Resumen conceptual

La jerarquía tiene tres capas:

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 extiende la RuntimeException de la SPL. Capturar RuntimeException también captura los errores de NextPDF. Capturar NextPdfException acota la captura a los errores del motor. Capturar una clase hoja permite una recuperación dirigida. El subárbol Strict\ agrupa las violaciones del modo de conformidad bajo la clase abstracta StrictModeViolation, que a su vez extiende NextPdfException.

Contexto, no códigos como cadenas. NextPDF identifica un error por su tipo de PHP, no por un código de error en cadena. No existe ninguna constante de código NPDF-#### en las clases de excepción. En su lugar, ContextAwareExceptionInterface::getContext() devuelve un array<string, mixed> de campos primitivos en snake_case, seguros para serializar en una carga útil de registro o de APM. NextPdfException::getContext() devuelve [] de forma predeterminada. Cada excepción de dominio sobrescribe ese método con los campos relevantes para ese fallo. Por ejemplo, FontNotFoundException::getContext() devuelve font_name, search_paths y fallback_attempted. WriterException devuelve output_path y writer_state. InvalidConfigException devuelve config_key, given_value y expected_type. Los identificadores de cadena estables e independientes NEXTPDF_W_* pertenecen al enum no fatal WarningCode del módulo Support, no a las excepciones.

Capacidad de acción. El docblock de clase de cada excepción de dominio indica quién puede actuar sobre ella: el desarrollador, la infraestructura o quien llama a la biblioteca. InvalidConfigException es un error del desarrollador (corregir la configuración). FontNotFoundException es un error del desarrollador o de la infraestructura (verificar la ruta o los permisos del archivo). WriterException es un error de la infraestructura (disco, permisos, flujo de salida). NotImplementedException es un error de quien llama (eliminar la llamada o fijar una versión que incorpore el seguimiento indicado). Varias excepciones incluyen constructores con nombre para causas raíz precisas —SignatureException::ltvCapabilityMissing(), ::tsaRequired() y similares—, de modo que los operadores vean la causa real en lugar de un mensaje genérico.

Superficie de la API

Símbolo	Tipo	Miembros clave
`NextPDF\Contracts\ContextAwareExceptionInterface`	interface	`getContext(): array<string, mixed>`
`NextPDF\Exception\NextPdfException`	clase abstracta	extiende `RuntimeException`; `getContext()` (predeterminado `[]`)
`NextPDF\Exception\InvalidConfigException`	final	`getConfigKey()`, `getGivenValue()`, `getExpectedType()`, `getContext()`
`NextPDF\Exception\FontNotFoundException`	final	`getFontName()`, `getSearchPaths()`, `wasFallbackAttempted()`, `getContext()`
`NextPDF\Exception\SignatureException`	final	`getCertInfo()`, `getSignatureLevel()`, `getDetail()`, `getContext()`; constructores con nombre `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	extiende `NextPdfException`
`NextPDF\Exception\Strict\IncompatibleRenderingModeException`	final	extiende `StrictModeViolation`

Conjunto completo de clases hoja (23): BarcodeEncoderNotFoundException, BarcodeException, CompressionException, ContentStreamBalanceException, CssParserLimitExceededException, CssResolutionBudgetExceededException, EncryptionException, FontNotFoundException, FontParsingException, GraphicsStateBalanceException, HtmlParsingException, ImageProcessingException, InvalidConfigException, LinearizationInvariantException, LinearizationUnimplementedException, MissingShadingResourceException, NotImplementedException, PageLayoutException, PdfRViolationException, SignatureException, TemplateException, UnsupportedAlgorithmException, WriterException.

Ejemplo de código — Inicio rápido

Capturar cualquier error del motor con el tipo base.

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

Este patrón está cubierto en examples/15-exception-handling.php.

Ejemplo de código — Producción

Recuperarse en el nivel de la clase hoja y reenviar el contexto estructurado a la canalización de registro.

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

Casos límite y trampas

El orden de captura importa. Enumerar las clases hoja antes de NextPdfException. Un catch (NextPdfException) situado primero absorbe todas las subclases.
getContext() usa claves en snake_case y valores primitivos o listas de primitivos —sin objetos anidados—, por lo que la carga útil siempre es segura para JSON.
La NextPdfException::getContext() base devuelve []. Una subclase que no sobrescribe ese método no contiene campos estructurados. Usar getMessage() en ese caso.
NextPdfException es abstracta: no puede instanciarse directamente. Lanzar una clase hoja concreta.
NotImplementedException es deliberadamente explícita: señala una implementación ausente de forma intencional, no un fallo transitorio. No reintentarlo.
Strict\* marca violaciones que indican un incumplimiento del contrato del modo de conformidad, no un error de ejecución recuperable. Tratarlas como defectos de configuración o de entrada.
No hay ninguna constante de código de error en cadena. Comparar por el tipo de la excepción. Reenviar getContext() a los consumidores automáticos.

Rendimiento

La construcción de una excepción consiste en una única asignación de objeto más el sprintf que construye el mensaje: O(1). getContext() devuelve un pequeño array asociativo construido a partir de campos ya disponibles, O(1) en el número de campos. Las excepciones son la ruta de fallo, no la ruta crítica de rendimiento. El costo es insignificante frente al trabajo que produjo el fallo. El performance_budget predeterminado para esta página de referencia es wall_ms: 1500, peak_mb: 64.

Notas de seguridad

Los campos de contexto pueden contener detalles derivados del documento: FontNotFoundException incluye las rutas de búsqueda del sistema de archivos, WriterException incluye la ruta de salida e InvalidConfigException incluye el valor proporcionado. Sanear o aplicar una lista de permitidos a las claves de contexto antes de reenviarlas a un destino de registro de baja confianza, ya que las rutas y los valores pueden revelar la disposición del despliegue o la entrada del usuario. Los mensajes de excepción son legibles por humanos y pueden incluir el mismo detalle: no exponer mensajes en bruto a los usuarios finales en un contexto sensible para la seguridad. SignatureException vincula deliberadamente la causa raíz concreta (paquete ausente, URL de TSA vacía) al mensaje, para que los operadores puedan hacer el triaje sin buscar por los puntos de llamada. Ese detalle está orientado al operador, no al usuario final.

Conformidad

Este módulo es un modelo de errores del motor y no incluye ninguna cita normativa de un estándar. Las excepciones que se lanzan por violaciones de estándares —por ejemplo PdfRViolationException o Strict\OracleConformanceFailure— hacen referencia a su cláusula rectora en el módulo que detecta la violación, no aquí.

Véase también

/modules/core/contracts/ — ContextAwareExceptionInterface, definición de la interfaz
/modules/core/observability/ — reenvío de getContext() al APM
/modules/core/config/ — InvalidConfigException, NotImplementedException
/modules/core/support/ — DegradedException; WarningCode (NEXTPDF_W_*)
/modules/core/event/ — InvalidConfigException desde addListener()

Glosario: excepción con conciencia de contexto · política de degradación