Errores del núcleo y generales

Alcance

Estas entradas cubren las excepciones del núcleo y de propósito general que lanza NextPDF. La mayoría extiende la base NextPdfException, que a su vez extiende \RuntimeException e implementa ContextAwareExceptionInterface. Esa interfaz expone un método, getContext(): array, que devuelve un mapa plano en snake_case de primitivos seguro para serializar a un registro o a una carga útil APM.

Capturar la familia NextPdfException con un único catch (NextPdfException $e). Añadir también un catch (\RuntimeException $e) para cubrir los pocos errores de bajo nivel de este conjunto que extienden directamente \RuntimeException (listados abajo). La base NextPdfException::getContext() devuelve un arreglo vacío; las subclases la redefinen para añadir campos de dominio. Donde una clase no redefine getContext(), hereda el arreglo vacío y el detalle de diagnóstico reside en su lugar en el mensaje y en los captadores tipados.

Cuatro tipos de este conjunto no extienden NextPdfException: BlackPointCompensationUnsupportedException y UnsupportedSourceDocumentException extienden directamente \RuntimeException (capturarlos como \RuntimeException), y ComplianceViolation y RuleViolation son objetos de valor, no excepciones: se documentan aquí porque modelan datos de error y de violación que el motor devuelve.

Excepción base

NextPdfException

• Qué es. Base abstract de toda excepción que lanza el núcleo de NextPDF y sus paquetes de extensión. Extiende \RuntimeException e implementa ContextAwareExceptionInterface. Capturar este único tipo intercepta cualquier error de la biblioteca.
• Contexto. La base getContext() devuelve un arreglo vacío. Las subclases la redefinen para devolver campos específicos del dominio.
• Recuperación. No se lanza directamente. Usarla como tipo comodín; ramificar según la subclase concreta para un manejo específico.

Configuración y habilitación de funcionalidades

InvalidConfigException

• Cuándo se lanza. Cuando un valor de Config o una combinación de valores es no válido: una opción obligatoria ausente, una opción mutuamente excluyente o un valor fuera de su rango aceptado. Esto señala un error del desarrollador: el código que llama suministró una configuración que debe corregirse antes de reintentar. El mensaje informa de la clave, el tipo o rango esperado y el tipo de depuración real del valor suministrado.
• Contexto. getContext() devuelve config_key, given_value y expected_type. Captadores tipados: getConfigKey(), getGivenValue(), getExpectedType().
• Recuperación. Acción del desarrollador: corregir la clave de configuración nombrada a un valor del tipo o rango esperado antes de volver a llamar a NextPDF.

NotImplementedException

• Cuándo se lanza. Cuando se alcanza un punto de entrada de la API pública pero su implementación está ausente de forma intencionada en la entrega actual. Se usa para adaptadores en desuso que existen para dar a los llamadores anteriores a la bisección un fallo ruidoso y accionable en lugar de una operación nula silenciosa. El mensaje combina una etiqueta feature rastreable por máquina y una referencia followUp (ID de defecto, ancla de seguimiento o nombre de sprint).
• Contexto. No redefine getContext(), de modo que devuelve un arreglo vacío. Los valores $feature y $followUp son propiedades públicas de solo lectura y se incrustan en el mensaje.
• Recuperación. Acción del llamador de la biblioteca: eliminar la llamada, o fijar la versión a una futura entrega que incorpore el seguimiento nombrado.

IncompatibleFeatureFlagsException

• Cuándo se lanza. En el momento de construir Config (Config::validate()) cuando una combinación de CssFeatureFlags es internamente inconsistente: una bandera presupone otra que está deshabilitada. La única combinación prohibida hoy es layoutSubgrid = true con layoutGrid = false: un eje con subcuadrícula deriva sus líneas de cuadrícula de un contenedor de cuadrícula padre (CSS Grid Layout Module Level 2 §1), de modo que la subcuadrícula sin cuadrícula describe una cuadrícula que no puede existir. La comprobación se ejecuta contra las banderas resueltas, de modo que CssRenderingMode::Safe (que fuerza la desactivación de toda funcionalidad de Fase 4 o posterior) enmascara la combinación en lugar de dispararla. Extiende StrictModeViolation.
• Contexto. getContext() fusiona los campos de modo estricto del padre (cssDeviation, excId, chunkSha256, location) con los booleanos layoutGrid y layoutSubgrid. La location es Config::validate() y cssDeviation codifica el par de banderas.
• Recuperación. Acción del llamador de la biblioteca: habilitar layoutGrid junto con layoutSubgrid, o deshabilitar layoutSubgrid.

IncompatibleRenderingModeException

• Cuándo se lanza. En el momento de construir Config cuando un emparejamiento de CssRenderingMode y CssLayoutMode cae fuera de las celdas compatibles de la matriz de modos. El único emparejamiento prohibido hoy es CssRenderingMode::Safe + CssLayoutMode::Retained: Safe fuerza la desactivación de toda funcionalidad de Fase 4 o posterior, lo que deja los contextos de formato en modo retenido (Grid, Subgrid, @container) sin consumidores, de modo que la combinación se rechaza en lugar de permitir que degrade en silencio. Extiende StrictModeViolation.
• Contexto. getContext() fusiona los campos de modo estricto del padre con mode1 (el valor del modo de representación) y mode2 (el valor del modo de maquetación). El cssDeviation codifica el par de modos; location es Config::validate().
• Recuperación. Acción del llamador de la biblioteca: elegir Safe + Streaming para revertir, o un modo de representación no Safe (Normal / Strict / Audit) con Retained para Grid / Subgrid / consultas de contenedor.

StrictModeViolation

• Cuándo se lanza. Base abstract de cualquier excepción de desviación de la especificación lanzada bajo CssRenderingMode::Strict. En modo estricto, cualquier desviación de CSS detectada que no esté vinculada a una entrada de excepción EXC-NNN registrada lanza una instancia de esta clase (o de una subclase) en el punto de detección. No se lanza directamente; véanse IncompatibleFeatureFlagsException e IncompatibleRenderingModeException.
• Contexto. getContext() devuelve los cuatro campos de ADR-023: cssDeviation (etiqueta corta de la construcción que se desvía), excId (identificador de registro cuando está registrada, si no null), chunkSha256 (hash del fragmento de citación de la especificación cuando se conoce, si no null) y location (origen legible por el llamador, si no null).
• Recuperación. Acción del llamador de la biblioteca: registrar la desviación como una nueva entrada EXC-NNN aprobada, o corregir el representador para eliminar la desviación.

Entrada de HTML y CSS

HtmlParsingException

• Cuándo se lanza. Cuando falla el análisis de la entrada HTML o la construcción del DOM: declaraciones de juego de caracteres no válidas, violaciones del límite de tamaño de entrada, profundidad de anidamiento excesiva, desbordamientos del recuento de elementos y errores de estructura de tabla como un máximo de recuento de filas. El agotamiento de recursos específico de CSS lo informan en su lugar CssParserLimitExceededException y CssResolutionBudgetExceededException.
• Contexto. getContext() devuelve html_snippet (un extracto corto y truncado del HTML infractor), position (desplazamiento en bytes, o -1 si se desconoce) y rule (la restricción de análisis violada). Captadores tipados: getHtmlSnippet(), getPosition(), getRule().
• Recuperación. Acción del desarrollador: simplificar la entrada HTML o ajustar los límites del analizador.

CssParserLimitExceededException

• Cuándo se lanza. Cuando la entrada CSS supera un límite de seguridad del analizador configurado. Se cubren dos categorías mediante los constructores con nombre: forByteLimit() (hoja de estilo demasiado grande para un procesamiento por regex seguro) y forNestingDepth() (recursión de anidamiento de CSS demasiado profunda). Ambos mensajes nombran el valor real y el límite.
• Contexto. getContext() devuelve limit_type (byte o nesting_depth), actual y limit.
• Recuperación. Acción del desarrollador: dividir la hoja de estilo en hojas más pequeñas, o reducir la profundidad de anidamiento, o elevar el límite configurado.

CssResolutionBudgetExceededException

• Cuándo se lanza. Cuando la resolución de :has() de CSS supera su presupuesto de recorrido. El resolutor de :has() de dos pasadas hace cumplir un presupuesto estricto de visitas a nodos para evitar que los selectores patológicos provoquen recorridos cuadráticos del documento; una vez que el recuento total de visitas supera el límite, la hoja de estilo se rechaza por demasiado compleja. El mensaje nombra el recuento de visitas y el presupuesto.
• Contexto. getContext() devuelve visits y budget. Captadores tipados: getVisits(), getBudget().
• Recuperación. Acción del desarrollador: reducir la complejidad de los selectores, o elevar el presupuesto configurado.

Fuentes e imágenes

FontNotFoundException

• Cuándo se lanza. Cuando un archivo de fuente no puede localizarse ni leerse a nivel de sistema de archivos: la familia o la ruta solicitada no existe, no es legible, o el directorio de fuentes configurado es inaccesible. Los datos de la fuente pueden ser válidos: esto señala únicamente que no se puede alcanzar. El mensaje lista las rutas buscadas.
• Contexto. getContext() devuelve font_name, search_paths (una lista) y fallback_attempted (un bool). Captadores tipados: getFontName(), getSearchPaths(), wasFallbackAttempted().
• Recuperación. Acción del desarrollador: verificar la ruta de la fuente. Acción de infraestructura: corregir los permisos de archivo del archivo o el directorio de la fuente.

FontParsingException

• Cuándo se lanza. Cuando se encuentra un archivo de fuente pero su contenido no es utilizable: está corrupto, en un formato no compatible o le faltan tablas obligatorias. Cubre fallos de validación estructural durante el análisis de TrueType, Type 1, CFF y OpenType: cabeceras truncadas, directorios de tablas no válidos, tablas obligatorias ausentes (head, hhea, OS/2), errores de desempaquetado y violaciones de tamaño. El mensaje nombra el archivo y el error de análisis.
• Contexto. getContext() devuelve font_file y parse_error. Captadores tipados: getFontFile(), getParseError().
• Recuperación. Acción del desarrollador: reemplazar el archivo de fuente por uno válido.

ImageProcessingException

• Cuándo se lanza. Cuando una imagen no puede decodificarse, está en un formato no compatible o no supera el procesamiento de GD/Imagick: bytes mágicos irreconocibles, datos JPEG corruptos, tipos MIME no compatibles, violaciones del límite de tamaño de archivo y fallos de asignación de recursos de GD. La imagen era accesible, pero sus datos de píxeles no pudieron extraerse para la incrustación.
• Contexto. getContext() devuelve image_path (vacío para datos en línea), format (detectado o esperado, p. ej. jpeg, png, unknown) y operation (p. ej. decode, resize, embed). Captadores tipados: getImagePath(), getFormat(), getOperation().
• Recuperación. Acción del desarrollador: suministrar un archivo de imagen válido y compatible.

Salida, maquetación y serialización

CompressionException

• Cuándo se lanza. Cuando la compresión o descompresión FlateDecode (zlib) falla: fallos de gzcompress/gzuncompress en flujos de contenido, datos de fuente, contenido de página, datos de adjuntos y flujos de referencias cruzadas. Normalmente un flujo de entrada corrupto, memoria insuficiente o una extensión zlib ausente.
• Contexto. getContext() devuelve algorithm (nombre del filtro, p. ej. FlateDecode, LZWDecode) y stream_length (longitud en bytes, o -1 si se desconoce). Captadores tipados: getAlgorithm(), getStreamLength().
• Recuperación. Acción de infraestructura: verificar que ext-zlib está cargada y que la memoria es suficiente.

WriterException

• Cuándo se lanza. Cuando la serialización, la linealización o la salida de E/S de PDF falla: errores de escritura de flujo de PdfWriter, corrupción de la tabla de referencias cruzadas, fallos de generación de cabecera/tráiler, fallos de resolución de referencias de objetos, errores de escritura de archivos y desbordamientos del búfer de salida. Un documento válido en memoria no pudo serializarse a un flujo de bytes válido. El mensaje nombra la etapa.
• Contexto. getContext() devuelve output_path (vacío para salida en cadena) y writer_state (la etapa, p. ej. header, body, xref, trailer). Captadores tipados: getOutputPath(), getWriterState().
• Recuperación. Acción de infraestructura: comprobar el espacio de disco, los permisos de archivo y el flujo de salida.

PageLayoutException

• Cuándo se lanza. Cuando las restricciones de maquetación de página no pueden satisfacerse: violaciones de la maquetación por columnas (ancho insuficiente, recuento de columnas no válido), desbordamiento de contenido más allá de los límites de página y conflictos de márgenes. La maquetación solicitada es geométricamente imposible para las dimensiones de página y el contenido dados. El mensaje nombra el número de página cuando se conoce y la restricción violada.
• Contexto. getContext() devuelve page_number (base uno, o 0 si se desconoce) y constraint. Captadores tipados: getPageNumber(), getConstraint().
• Recuperación. Acción del desarrollador: ajustar el tamaño de página, los márgenes, los ajustes de columnas o el contenido.

TemplateException

• Cuándo se lanza. Cuando una operación de importación o reutilización de plantillas PDF falla en TemplateManager: transiciones de estado de plantilla no válidas (iniciar o finalizar plantillas fuera de secuencia), referenciar una plantilla inexistente y fallos de compresión de flujo durante la serialización de la plantilla. El mensaje nombra la operación y el id de la plantilla cuando está asignado.
• Contexto. getContext() devuelve template_id (vacío si aún no está asignado) y operation (p. ej. begin, end, use, serialize). Captadores tipados: getTemplateId(), getOperation().
• Recuperación. Acción del desarrollador: corregir la secuencia de uso de la plantilla o el PDF de origen.

Invariantes del flujo de contenido

ContentStreamBalanceException

• Cuándo se lanza. Cuando un ContentStreamBuilder detecta un par de operadores desequilibrado al cerrar el flujo (o a mitad de flujo cuando los invariantes se afirman de forma anticipada). Captura los contadores de profundidad que no superaron el invariante de equilibrio para que el registro pueda identificar qué emisor dejó escapar un q, BT o BMC sin su Q, ET o EMC correspondiente. Conforme a ISO 32000-2:2020 §8.4.2 (pila del estado gráfico), §9.4.1 (objetos de texto) y §14.6 (contenido marcado).
• Contexto. getContext() devuelve graphics_depth, text_block_depth, marked_content_depth y offending_operator. Captadores tipados: getGraphicsDepth(), getTextBlockDepth(), getMarkedContentDepth(), getOffendingOperator().
• Recuperación. Acción del desarrollador: localizar el emisor que abrió una construcción sin cerrarla.

GraphicsStateBalanceException

• Cuándo se lanza. Cuando un flujo de contenido PDF se cierra con operadores q/Q desequilibrados. ISO 32000-2:2020 §8.4.2 exige que cada guardado del estado gráfico (q) tenga exactamente una restauración (Q) correspondiente antes de que el flujo termine; el desequilibrio deja escapar transformaciones, rutas de recorte, colores e intención de representación a las páginas posteriores o a los Form XObjects. Se lanza solo cuando la comprobación estricta del estado gráfico está habilitada (NEXTPDF_GFXSTATE_STRICT=1); en modo relajado se emite en su lugar una advertencia vía trigger_error().
• Contexto. getContext() devuelve save_depth (positivo si hay demasiados guardados, negativo si hay demasiadas restauraciones). Captador tipado: getSaveDepth().
• Recuperación. Acción del desarrollador: localizar el par save()/restore() sin correspondencia.

MissingShadingResourceException

• Cuándo se lanza. Cuando se invoca ConicGradientRenderer::render() sin un contexto de registro de recursos de sombreado. El cambio incompatible de la v10.0.0 eliminó la anterior vía sustituta de mapa de marcadores implícito: los llamadores deben construir el representador con un ShadingResourceRegistryInterface para que el objeto indirecto /ShadingType 4 se registre contra el subdiccionario de recursos de sombreado de la página (ISO 32000-2 §8.7.4.2 / §8.7.4.3). El mensaje nombra el contexto del llamador y apunta a la nota de migración de v9.x→v10.0.
• Contexto. getContext() devuelve context (una etiqueta corta de contexto del llamador, p. ej. ConicGradientRenderer::render).
• Recuperación. Acción del llamador de la biblioteca: conectar una instancia de registro de recursos de sombreado al constructor del representador antes de llamar a render().

Linealización (vista web rápida)

LinearizationInvariantException

• Cuándo se lanza. Cuando el Linearizer de tres pasadas de la v2 detecta que se violaron sus aserciones MEASURE → PLACE → FILL: un recuento de bytes de la Pasada 3 que no coincide con la longitud de archivo predicha en la Pasada 1 (deriva de desplazamiento), un marcador de posición del diccionario de linealización demasiado pequeño para el ancho serializado, o un desplazamiento de flujo de pistas /H [offset length] que no coincide con la salida final. Aflorar esto en lugar de emitir un PDF roto es una garantía de seguridad declarada.
• Contexto. getContext() devuelve invariant (el nombre del invariante violado), expected, actual y delta (la diferencia con signo). Captadores tipados: getInvariant(), getExpectedValue(), getActualValue().
• Recuperación. Acción del mantenedor: presentar un informe de errores; estos invariantes deberían cumplirse para todas las entradas bien formadas. Capturar la excepción previa encadenada.

LinearizationUnimplementedException

• Cuándo se lanza. Cuando la bandera de funcionalidad del linealizador se fija en una dorsal deshabilitada de forma intencionada. Actualmente se lanza solo para linearizerVersion === 'v1-noop', la configuración de degradación de emergencia que rechaza todos los intentos de linealización en tiempo de ejecución sin un cambio de código ni un redespliegue, útil para desactivar la vista web rápida en producción mediante interruptor de apagado.
• Contexto. getContext() devuelve reason (una explicación corta legible). Captador tipado: getReason().
• Recuperación. Acción del operador o de ingeniería de entregas: ajustar la configuración o actualizar a una versión de dorsal corregida.

Invariantes de conformidad y de perfil

ConformanceViolationException

• Cuándo se lanza. Cuando una funcionalidad solicitada no puede emitirse sin romper el contrato de conformidad ISO declarado del documento, y el motor falla de forma cerrada en lugar de escribir un objeto no conforme. El desencadenante canónico es una anotación multimedia Screen o una acción Rendition (ISO 32000-2:2020 §12.5.6.18 / §13.2) bajo un perfil de archivo PDF/A, que toda parte de PDF/A prohíbe (serie ISO 19005): el archivo no superaría la validación de veraPDF, de modo que el motor se niega de antemano.
• Contexto. getContext() devuelve conformance_mode (el modo declarado, p. ej. pdfa4) y feature (la funcionalidad rechazada, p. ej. Screen annotation). Ambas son propiedades públicas de solo lectura. El motivo es el mensaje de la excepción.
• Recuperación. Acción del desarrollador: eliminar la llamada multimedia para la salida de archivo, o apuntar a un perfil de conformidad no de archivo (el predeterminado ConformanceMode::Plain).

PdfRViolationException

• Cuándo se lanza. Cuando se viola un invariante de conformidad PDF/R-1 (ISO 23504-1:2020), bien en la construcción del objeto de valor (los perfiles PdfRStrip, PdfRPage, PdfRDocument), bien en el momento del validador (PdfRValidator). Captura la cláusula normativa infractora y una descripción de la violación en una línea para que los consumidores de auditoría puedan encaminar los hallazgos a la subcláusula §6 correcta sin analizar texto libre.
• Contexto. getContext() devuelve standard (siempre ISO 23504-1:2020), clause (la ruta de la cláusula, p. ej. 6.6.1) y violation. Captadores tipados: getClause(), getViolation().
• Recuperación. Acción del desarrollador: corregir la entrada rechazada o reconstruir el documento para que se ajuste a la cláusula citada.

Generación de códigos de barras

BarcodeException

• Cuándo se lanza. Cuando la generación de un código de barras falla por datos no válidos o errores de codificación en todas las simbologías compatibles (Code 39/128, UPC-A/E, EAN-8/13, Interleaved/Standard 2-of-5, POSTNET, PLANET, MSI, ISBN, ISSN, QR Code, PDF417, DataMatrix, JabCode) y por fallos de representación de GD durante la creación de la imagen. El valor del código de barras se limita a un extracto de 128 bytes en el mensaje y el contexto: las cargas útiles sobrelargas o binarias se almacenan truncadas con un marcador ... (<N> bytes, truncated) para que no puedan copiarse enteras a un registro.
• Contexto. getContext() devuelve barcode_type (simbología, p. ej. QRCODE, EAN13, CODE128) y value (el valor truncado). Captadores tipados: getBarcodeType(), getValue().
• Recuperación. Acción del desarrollador: corregir los datos del código de barras o la selección de simbología.

BarcodeEncoderNotFoundException

• Cuándo se lanza. Desde BarcodeEncoderRegistry cuando el tipo de codificador solicitado es desconocido o su puerta de capacidad está cerrada. También implementa Psr\Container\NotFoundExceptionInterface de PSR-11, de modo que el registro es un contenedor conforme a estándares. El mensaje nombra la simbología y el motivo.
• Contexto. No redefine getContext(), de modo que devuelve un arreglo vacío. El type y el reason están disponibles a través de los captadores getType() y getReason() y en el mensaje.
• Recuperación. Acción del desarrollador: registrar el codificador, o instalar el paquete que lo proporciona (por ejemplo nextpdf/pro para Micro QR / DotCode / HanXin / JabCode).

Criptografía, cifrado y firmas

EncryptionException

• Cuándo se lanza. Cuando el cifrado o descifrado de PDF falla: fallos de cifrado/descifrado AES-256-CBC, errores de OpenSSL, tamaños de IV no válidos, fallos de cálculo de hash y errores de cálculo de los valores UE/OE. Normalmente una extensión OpenSSL ausente o mal configurada, material de clave no válido o datos cifrados corruptos. El mensaje nombra la operación y el algoritmo.
• Contexto. getContext() devuelve algorithm (p. ej. AES-256-CBC) y operation (p. ej. encrypt, decrypt, key_derivation). Captadores tipados: getAlgorithm(), getOperation().
• Recuperación. Acción de infraestructura: asegurarse de que OpenSSL está disponible y correctamente configurado. Véase Cifrado y permisos.

UnsupportedAlgorithmException

• Cuándo se lanza. Cuando un algoritmo criptográfico no puede ejecutarse en el entorno de ejecución actual: una extensión de PHP requerida no está disponible, la biblioteca subyacente carece de la primitiva, la extensión hash incluida no puede sintetizar una variante SHAKE/XOF, o el algoritmo no está registrado en el SignatureAlgorithmRegistry. El motor no debe degradar de forma silenciosa a una primitiva más débil, de modo que aflora esto en su lugar. La fábrica estática nonFipsHostUnderFipsProfile() la lanza (con el identificador de algoritmo regulatory-profile:fips) cuando se selecciona RegulatoryProfile::FIPS pero no puede confirmarse un proveedor OpenSSL validado por FIPS (tanto FIPS_ABSENT como INDETERMINATE fallan de forma cerrada).
• Contexto. getContext() devuelve algorithm (nombre u OID, p. ej. shake256, Ed25519, AES-256-GCM) y reason (accionable por el operador). Captadores tipados: getAlgorithm(), getReason().
• Recuperación. Acción del operador: instalar la extensión ausente o actualizar el entorno de ejecución; para la puerta FIPS, instalar una compilación OpenSSL validada por FIPS o fijar NEXTPDF_FIPS_MODE explícitamente. Acción del desarrollador: registrar un descriptor de algoritmo personalizado vía SignatureAlgorithmRegistry::register().

SignatureException

• Cuándo se lanza. Cuando una operación de firma digital falla: manejo de certificados y claves privadas (análisis PKCS#12, decodificación PEM/DER, validación X.509), construcción PKCS#7/CMS, formato de firma ECDSA, violaciones del tamaño del contenedor, codificación DER y orquestación PAdES. Los errores específicos de TSA los informa en su lugar la más específica TsaException. Preferir las fábricas tipadas con nombre al constructor posicional; cada una vincula la causa raíz al final del mensaje. Ejemplos: ltvCapabilityMissing() (B-LT/B-LTA necesita nextpdf/enterprise), tsaRequired() / tsaUrlEmpty() / tsaEmptyToken(), httpClientMissing(), hsmSignerMissing() / hsmSignatureEmpty(), signatureContentsNotFound() / signatureContentsPaddingCorrupt(), unexpectedKeyType(), pemDecodingFailed(), la familia Ed25519 (ed25519SignatureMalformed(), ed25519RoundTripVerifyFailed(), ed25519KeyParseFailed(), ed25519SeedInvalid(), ed25519SecretKeyMalformed(), ed25519PublicKeyInvalid()), documentTimestampNotEmitted(), algorithmPolicyRejected(), digestOnlyAlgorithmRefused(), encryptedLtvUnsupported(), incrementalUpdateWriterMissing() y el par de estado OCSP nonSuccessfulOcspResponseStatus() / reservedOcspResponseStatus() (RFC 6960 §4.2.1). Estas fábricas fallan de forma cerrada en lugar de emitir una firma silenciosamente rebajada de nivel.
• Contexto. getContext() devuelve cert_info (DN del sujeto o huella digital, o vacío), signature_level (el nivel PAdES intentado, p. ej. B-B, B-T, B-LT, B-LTA) y detail (el diagnóstico accionable, vacío para el constructor posicional heredado). Captadores tipados: getCertInfo(), getSignatureLevel(), getDetail().
• Recuperación. Acción del desarrollador: corregir la configuración de certificado/clave. Para las fábricas de capacidad ausente, instalar el paquete nombrado. Véase Fallos de firma y marca de tiempo para las entradas de síntoma y resolución por fábrica.

BlackPointCompensationUnsupportedException

• Cuándo se lanza. Desde NullBlackPointCompensationTransform::transform() cuando un llamador le pide al adaptador nulo aplicar una transformación de compensación de punto negro de ISO 18619 que no es Default. El adaptador nulo es el repliegue seguro para entornos sin una dorsal de gestión de color; producir una muestra transformada sin un módulo de gestión de color real informaría de la conversión de forma errónea y silenciosa. A diferencia de la mayoría de las entradas de aquí, esta extiende directamente \RuntimeException, no NextPdfException, de modo que las vías catch (\RuntimeException) existentes siguen funcionando.
• Contexto. Sin getContext(); es una \RuntimeException simple. El detalle está en el mensaje.
• Recuperación. Acción del desarrollador: registrar una BlackPointCompensationTransform real (LittleCMS, Argyll, PHP puro), o restringir /UseBlackPtComp a BlackPointCompensation::Default.

Ensamblaje del documento y accesibilidad

UnsupportedSourceDocumentException

• Cuándo se lanza. Cuando un documento de origen no puede copiarse de forma segura a una salida de fusión/división y la operación falla de forma cerrada en lugar de emitir un resultado corrupto o con la seguridad comprometida. Usar las fábricas con nombre: encrypted() (ISO 32000-2 §7.6: el contenido no puede copiarse sin la clave), signed() (§12.8: copiar páginas invalidaría el rango de bytes de la firma), unsupportedStreamFilter() (un filtro que el lector del grafo de objetos no puede recorrer en ambos sentidos), multipleInteractiveForms() (una limitación documentada: más de un origen porta un /AcroForm no vacío, §12.7) y splitWithInteractiveForm() (una limitación documentada: subseleccionar páginas de un origen con formulario dejaría huérfanos los widgets). Extiende directamente \RuntimeException, no NextPdfException.
• Contexto. Sin getContext(); es una \RuntimeException simple. La causa y el número de objeto afectado se nombran en el mensaje.
• Recuperación. Acción del desarrollador: descifrar primero el origen o suministrar la clave; para orígenes firmados, firmar después de fusionar; para fusiones de varios formularios, aplanar o eliminar los campos de formulario de todos los orígenes menos uno; para divisiones de orígenes con formulario, aplanar el formulario antes de dividir.

InvalidBcp47TagException

• Cuándo se lanza. Desde Bcp47Validator::validate() cuando una etiqueta de idioma candidata está malformada bajo el ABNF de RFC 5646 §2.1, o no supera la búsqueda en el registro curado. Específica del dominio de BCP-47 / ISO 14289-2:2024 §8.4.4, distinta de InvalidConfigException para que los llamadores aguas abajo de la costura de accesibilidad puedan capturar un tipo estrecho. El par de predicados Bcp47Validator::isWellFormed() / isValid() sigue siendo la superficie de valor de retorno compatible hacia atrás para los llamadores que prefieren ramificar a usar excepciones.
• Contexto. getContext() devuelve tag (el candidato exactamente como se suministró) y reason (un código de rechazo estable legible por máquina, p. ej. empty-string, well-formed-shape, unregistered-primary, duplicate-variant). Captadores tipados: getTag(), getReason().
• Recuperación. Acción del desarrollador: corregir la etiqueta de idioma a una etiqueta BCP-47 bien formada y registrada. Véase Fuentes y etiquetado.

FormFieldAccessibilityException

• Cuándo se lanza. Cuando un campo de formulario interactivo dependería de un nombre accesible sintético (no suministrado por el autor) al producir un documento PDF/UA con la aplicación estricta de nombres de campo accesibles habilitada. La salida PDF/UA predeterminada emite un nombre de repliegue sintético en el /Contents del widget para que un campo nunca quede sin nombre; el modo estricto, en cambio, exige que el autor suministre un nombre significativo (una descripción emergente, o un rótulo para un botón pulsador sin acción) para que los usuarios de lectores de pantalla obtengan una descripción real (ISO 14289-2:2024 §8.10.2).
• Contexto. No redefine getContext(), de modo que devuelve un arreglo vacío. El $fieldId es una propiedad pública de solo lectura; el motivo es el mensaje.
• Recuperación. Acción del desarrollador: suministrar una descripción emergente o un nombre accesible para el campo nombrado antes de producir un documento PDF/UA estricto, o deshabilitar el modo estricto. Véase Validación de PDF/A y PDF/UA.

VendorExtensionRegistryConflictException

• Cuándo se lanza. Desde VendorExtensionRegistry::register() cuando un llamador vuelve a registrar un prefijo de proveedor de extensiones de desarrollador de PDF conocido (ISO 32000-2:2020 §7.12.1) con una descripción que difiere de los metadatos ya registrados. Los descriptores son de solo añadir y con detección de conflictos; la excepción tipada reemplazó una \RuntimeException genérica para que los llamadores puedan capturar esta clase específica.
• Contexto. getContext() devuelve prefix, existing_description y attempted_description. Captadores tipados: getPrefix(), getExistingDescription(), getAttemptedDescription().
• Recuperación. Acción del desarrollador: registrar el prefijo con la descripción existente, o usar un prefijo distinto; no sobrescribir metadatos registrados.

Exportación de auditoría

AuditExportException

• Cuándo se lanza. Cuando el ensamblaje del paquete de exportación de auditoría, la generación de la matriz de trazabilidad o la proyección de esquema falla en tiempo de ejecución. Cubre la E/S contra claims.json / manifest.json, la codificación/decodificación JSON del paquete canónico y el desajuste de versión de esquema en la vía compatible hacia atrás AuditExporter::projectToV1(). El mensaje nombra la etapa, el artefacto cuando se conoce y el detalle.
• Contexto. getContext() devuelve stage (p. ej. read_claims, encode_bundle, project_v1), detail y artefact (la ruta o la schema_version que desencadenó el fallo). Captadores tipados: getStage(), getDetail(), getArtefact().
• Recuperación. Acción de conformidad / DevOps: verificar las rutas de los artefactos de entrada, regenerar claims.json a partir de una ejecución limpia, o reconstruir el manifiesto antes de reintentar la exportación.

Objetos de valor de violación

Estos no son excepciones. Son objetos de valor inmutables que el motor devuelve para describir una violación individual; no transportan getContext().

ComplianceViolation

• Qué es. Un objeto de valor final readonly que representa un fallo de regla reportado por un validador externo (veraPDF o equivalente), incluida la referencia de cláusula ISO y la ubicación dentro de la estructura del PDF.
• Campos. Propiedades públicas de solo lectura: ruleId (identificador de regla del validador, p. ej. 6.1.2-1), clause (referencia de cláusula ISO, p. ej. ISO 19005-1:2005, 6.1.2), severity (p. ej. error, warning), location (ruta del objeto dentro de la estructura del PDF) y message (descripción legible).
• Uso. Inspeccionar la colección que devuelve un validador de conformidad; encaminar o mostrar cada entrada según severity y clause. Véase Validación de PDF/A y PDF/UA.

RuleViolation

• Qué es. Un objeto de valor final readonly que representa una violación de regla de negocio de Schematron / EN 16931, devuelta por SchematronRunnerInterface::runRules() y agregada dentro de ValidationResult::$ruleViolations. La estabilidad es experimental.
• Campos. Propiedades públicas de solo lectura: ruleId (identificador de EN 16931 como BR-{n}, BR-CO-{n}, BR-CL-{n}, BR-DEC-{n}, o un paquete específico de nivel), severity (una enumeración RuleSeverity), message (texto de la regla, en-GB), xpath (XPath en el XML incrustado, null para reglas de todo el documento) y semanticPath (ruta BG/BT en notación de puntos como BG-22.BT-106, null para violaciones estructurales).
• Uso. Inspeccionar la colección del resultado de la validación; encaminar o mostrar cada entrada según severity, ruleId y el localizador.

Véase también

• Índice de la referencia de errores
• Índice de la base de conocimientos
• Fallos de firma y marca de tiempo
• Cifrado y permisos
• Fuentes y etiquetado
• Validación de PDF/A y PDF/UA