Base de conocimiento para resolver problemas

Qué cubre esta base de conocimiento

Esta base de conocimiento relaciona los fallos observados con su causa y solución. Cada entrada se basa en las propias clases de excepción del motor, en las pruebas de la ruta de fallo y en las protecciones del código fuente, no en especulaciones. Si en el motor no existe ninguna ruta de código que produzca un fallo determinado, esta base de conocimiento no lo inventa.

La base de conocimiento se organiza en cuatro páginas temáticas:

• Validación de firmas: firma no válida, cadena incompleta, revocación desconocida y fallos de marca de tiempo.
• Validación de PDF/A y PDF/UA: falta de output intent, contenido sin etiquetar, falta de idioma y fallos de fuentes incrustadas.
• Fuentes y etiquetado: fuente no encontrada, subconjuntos, cobertura CJK y problemas en el árbol de estructura.
• Cifrado y permisos: fallos de descifrado y el límite de los indicadores de permisos.

Cómo leer una entrada

Cada entrada consta de cinco partes:

1. Síntoma: lo que se observa, ya sea una clase de excepción, un fragmento de mensaje o el veredicto de un validador posterior.
2. Causa probable: la condición de entrada o configuración que informa el motor.
3. Evidencia / diagnóstico: cómo confirmar la causa. Se nombra la clase de excepción exacta, el campo getContext() o la prueba que demuestra el comportamiento, para poder verificar en lugar de suponer.
4. Solución: los pasos para eliminar la causa, redactados como un procedimiento ordenado.
5. Relacionado: la página de referencia del módulo o la entrada hermana que conviene leer a continuación.

Identificar un fallo por tipo de excepción

NextPDF identifica los errores por su clase PHP, no por un código de error en forma de cadena. No existe ninguna constante NPDF-#### en las clases de excepción. Capturar la excepción hoja permite responder de forma precisa y leer ContextAwareExceptionInterface::getContext() para obtener campos de diagnóstico estructurados. El tipo base es NextPDF\Exception\NextPdfException; los fallos de seguridad usan además NextPDF\Security\Exception\SecurityException.

Para conocer la jerarquía completa y las reglas de orden de captura, consultar la referencia de excepciones.

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

Alcance y límites

Esta base de conocimiento describe cómo se detectan y notifican los fallos dentro del motor. No describe el veredicto de conformidad emitido por un validador externo, como veraPDF o callas; esas herramientas aplican sus propios conjuntos de reglas. Cuando el motor rechaza una operación para mantener un documento dentro de un perfil (por ejemplo, al rechazar el cifrado bajo PDF/A), la entrada correspondiente cita la cláusula rectora y la excepción que la aplica.

Véase también

• Referencia de excepciones: jerarquía completa, orden de captura, getContext() y su contrato
• Referencia de conformidad: verificadores de perfil PDF/A, PDF/UA y PDF/X

Glosario: excepción con reconocimiento de contexto