Errores de conformidad

Alcance

Estas entradas cubren las dos excepciones del espacio de nombres NextPDF\Compliance\Exception. Ambas las lanza el subsistema de conformidad: la canalización canónica de hash de cláusula y el ciclo de vida de conformidad (la caché de evidencias de conformidad del documento, el promotor de auditado a terminal y el observador de enfriamiento).

Ambas clases son final y extienden NextPdfException, que a su vez extiende \RuntimeException e implementa ContextAwareExceptionInterface. Ninguna de las subclases redefine getContext(), de modo que ambas heredan la implementación base, que devuelve un arreglo vacío. El detalle de diagnóstico se transporta en el mensaje de la excepción, no en getContext(). Capturar cualquiera de los dos tipos como NextPdfException, o como \RuntimeException si se dispone de manejadores existentes.

Requisitos de tiempo de ejecución del hash de cláusula

ClauseHashRequirementException

• Cuándo se lanza. Desde ClauseHash::compute() cuando el entorno de ejecución de PHP anfitrión carece de un requisito imprescindible de la canalización canónica de hash de cláusula. Actualmente el único requisito de ese tipo es ext-intl, usado para la normalización Unicode en Forma de Normalización KC (NFKC). El único punto de lanzamiento genera el mensaje ClauseHash requires ext-intl for NFKC normalisation.
• Por qué falla de forma cerrada. composer.json exige ext-intl, de modo que esto solo se dispara en un consumidor descendente mal configurado que empaqueta NextPDF sin intl. La canalización se niega a calcular un resumen sin normalización NFKC en lugar de emitir de forma silenciosa un hash incompatible con todos los demás consumidores de hash de cláusula.
• Contexto. getContext() devuelve un arreglo vacío. La causa se indica en el mensaje.
• Recuperación. Acción del operador: instalar y habilitar la extensión intl de PHP en el anfitrión, y luego reintentar. No hay solución alternativa en código; el resumen normalizado no puede producirse sin ella.

Fallos del ciclo de vida de conformidad

ComplianceLifecycleException

• Cuándo se lanza. Desde el subsistema del ciclo de vida de conformidad cuando se viola en tiempo de ejecución un invariante estructural de claims.json o de su canalización de persistencia. Los puntos de lanzamiento abarcan el promotor de auditado a terminal, el observador de enfriamiento y la caché incremental de evidencias de conformidad del documento. Los desencadenantes concretos son:
  • Documento raíz malformado: claims.json no se decodifica a un objeto, o claims.standards no es un objeto JSON (por ejemplo, claims.json must decode to an object, claims.standards must be a JSON object, claims.json invalid JSON: <detail>).
  • Fallos de lectura: claims.json falta o no es legible (por ejemplo, claims.json not found at: <path>, claims.json unreadable at <path>).
  • Fallos de E/S de escritura atómica en la canalización de persistencia: apertura del temporal, flock, escritura corta, fflush, rename atómico y escritura del sidecar (por ejemplo, tmp open failed at <path>, tmp flock failed at <path>, tmp write short for <path>, tmp fflush failed at <path>, atomic rename failed for <path>, sha256 sidecar write failed at <path>).
  • Fallos del lado del codificador: json_encode() rechaza la carga útil saliente (por ejemplo, claims.json encode failed: <detail>).
  • Fallos de arranque de la caché de evidencias: la caché incremental no puede crear ni escribir en su directorio raíz (por ejemplo, IncrementalEvidenceCache: cannot create rootDir <path>, IncrementalEvidenceCache: write failed for <path>, IncrementalEvidenceCache: rename failed for <path>).
  • Vulneraciones de invariantes internos: por ejemplo un gmdate produced empty timestamp o fqClauseId: empty clauseKey.
• Por qué existe. Es un reemplazo con tipo de dominio del uso anterior de \RuntimeException en el código del ciclo de vida y de la caché. No cambia el contrato de tiempo de ejecución, porque NextPdfException ya extiende \RuntimeException; las cláusulas catch (\RuntimeException $e) existentes siguen funcionando.
• Contexto. getContext() devuelve un arreglo vacío. La ruta infractora y el fallo específico se nombran en el mensaje; los fallos de decodificación y codificación JSON encadenan además la \JsonException subyacente como excepción previa, de modo que conviene leer getPrevious() para esos casos.
• Recuperación.
  • Para errores de forma y de lectura, se trata de una acción del operador: inspeccionar claims.json en la ruta nombrada en el mensaje, confirmar que es JSON bien formado cuya raíz y cuyo miembro standards son objetos, y confirmar que está presente y es legible.
  • Para errores de escritura atómica y de arranque de la caché, comprobar la existencia, los permisos y el espacio libre del directorio de destino, y luego reintentar.
  • Para fallos del lado del codificador, se trata de una acción del desarrollador: la carga útil entregada a json_encode() no es codificable. Capturar la excepción previa encadenada y el mensaje para un informe de defectos.

Véase también

• Índice de la referencia de errores
• Validación de PDF/A y PDF/UA