Errores de representación y de E/S

Alcance

Estas entradas cubren las excepciones de representación y de entrada/salida (E/S) que se lanzan mientras la canalización HTML maqueta el contenido, el resolutor de soportes paginados asigna la geometría de página, el conformador de texto procesa escrituras complejas, la etapa tipográfica divide las líneas, el escritor serializa un documento, el lector analiza un PDF existente y la etapa de metadatos lee un paquete de la Plataforma Extensible de Metadatos (XMP).

A continuación aparecen dos jerarquías base, y la diferencia gobierna qué datos de diagnóstico se pueden leer tras un catch:

• NextPdfException implementa ContextAwareExceptionInterface::getContext(): array. La implementación base devuelve un arreglo vacío; una subclase transporta claves estructuradas solo cuando redefine getContext(). Las subclases que no la redefinen exponen aun así sus datos a través de propiedades public readonly.
• Varias clases aquí extienden directamente RuntimeException de PHP. No son conscientes del contexto y no tienen método getContext(); léase su getMessage() y cualquier propiedad pública en su lugar.

Cada entrada nombra la clase exacta, la condición desencadenante, las claves de contexto o las propiedades públicas que transporta y la vía de recuperación.

Maquetación HTML y soportes paginados

UnsplittableContentException

• Cuándo se lanza. El motor de maquetación HTML lanza esto cuando un contenido marcado break-inside: avoid (una celda de tabla cuya restricción de salto es Avoid) tiene una altura medida que supera la altura útil de una sola página. El motor no puede satisfacer a la vez la restricción de evitar el salto y el límite de página, por lo que falla en lugar de desbordar de forma silenciosa.
• Datos transportados. Extiende NextPdfException pero no redefine getContext(), de modo que getContext() devuelve un arreglo vacío. Los datos de diagnóstico están en propiedades public readonly: gridRow (int), gridCol (int), contentHeight (float, puntos) y pageHeight (float, puntos). El mensaje nombra las coordenadas de la celda y ambas alturas.
• Recuperación. Eliminar la restricción break-inside: avoid de la celda infractora, reducir el contenido de la celda para que quepa en una página, o aumentar el tamaño de página o reducir sus márgenes para que la altura útil acomode el contenido.

BudgetExceededException

• Cuándo se lanza. Las primitivas de maquetación en modo retenido lanzan esto cuando se supera uno de los cuatro niveles de presupuesto de recursos definidos en el registro de decisión arquitectónica ADR-020 y el llamador optó por un fallo duro en lugar del repliegue blando. La vía predeterminada no lanza: ContainerLayout::acceptChild() devuelve false, el llamador recurre a la maquetación por bloques y se emite una advertencia. La excepción se reserva para la validación en tiempo de configuración y para pruebas que afirman la tupla exacta de la infracción. Los niveles son per-child (un flujo de hijo capturado supera su tope), per-container (el presupuesto de recuento de nodos de Nivel 1), per-document (el presupuesto de pasadas de maquetación o de profundidad de anidamiento) y global (el tope de 256 MB de tamaño máximo de conjunto residente para todo el SDK).
• Datos transportados. Redefine getContext(), que devuelve una forma estable de ocho claves que consume el instrumental de supervisión del rendimiento de aplicaciones (APM): budgetTier, exceededValue, budgetLimit, containerType, phase, breachOrigin, captureSize y processedItemCount. Las primeras cuatro claves son el subconjunto original de la v1.0.0 y siempre se rellenan; las últimas cuatro toman null o 0 por defecto cuando el constructor se llama sin ellas. getCausalWarningCode() asigna la tupla (nivel, tipo de contenedor) al WarningCode que la vía de repliegue blando habría emitido.
• Recuperación. Ante una infracción de configuración, reducir el valor solicitado de nuevo al rango documentado (por ejemplo, el presupuesto de nodos retenidos acepta de 5000 a 100 000 mediante Config::withRetainedNodeBudget()). Ante una infracción de contenido, reducir el anidamiento de contenedores o el recuento de nodos, o confiar en el repliegue blando predeterminado a la maquetación por bloques en lugar de optar por la superficie de fallo duro.

UnsupportedNamedPageException

• Cuándo se lanza. La etapa de soportes paginados lanza esto, de forma cerrada, cuando un documento declara una regla @page <ident> { … } con nombre (vinculada al contenido a través de la propiedad page: <ident>). Las páginas con nombre de CSS Paged Media Level 3 §3.4 y Level 4 §3.2 —incluidas las pseudoclases :first, :left, :right y :blank y los reemplazos size: y rotate: con nombre— se analizan, pero ninguna vía de maquetación de producción las consume. El motor se niega en lugar de emitir la paginación predeterminada silenciosamente incorrecta que produciría descartar la regla.
• Datos transportados. Redefine getContext(), que devuelve page_names (lista de los identificadores distintos que desencadenaron el fallo, en orden de origen), has_size_override (bool), has_rotate_override (bool) y has_pseudo_classes (bool). Los mismos valores se exponen en las propiedades públicas pageNames, hasSizeOverride, hasRotateOverride y hasPseudoClasses.
• Recuperación. Eliminar las reglas @page <ident> con nombre y cualquier vínculo page: <ident>, y expresar la geometría prevista a través de la regla @page { … } sin nombre compatible y sus formas de pseudoclase. Alternativamente, fijar la versión a una futura entrega que incorpore soporte completo de maquetación de páginas con nombre.

Tipografía y conformado de texto

IcuRequirementException

• Cuándo se lanza. La segmentación de texto lanza esto cuando necesita el iterador de salto de línea de los Componentes Internacionales para Unicode (ICU) pero la política de exigir ICU está activa (NEXTPDF_REQUIRE_ICU=1) mientras la extensión ext-intl y IntlBreakIterator no están disponibles.
• Datos transportados. Extiende directamente RuntimeException, de modo que no es consciente del contexto y no tiene getContext(). Es un refinamiento estricto de la excepción genérica que la misma vía de código lanzaba antes, de modo que los manejadores catch (\RuntimeException) existentes siguen funcionando.
• Recuperación. Instalar y habilitar ext-intl para que el iterador de salto ICU esté disponible, o desfijar NEXTPDF_REQUIRE_ICU para recurrir al segmentador no ICU donde la política de exigir ICU no es obligatoria.

ScriptShaperException

• Cuándo se lanza. Es la excepción base de la interfaz de proveedor de servicios (SPI) de conformado de escrituras. Hoy no se lanza directamente; en su lugar se lanzan subtipos concretos. Capturar este tipo para manejar en un único lugar cualquier fallo de conformado.
• Datos transportados. Extiende directamente RuntimeException; no consciente del contexto, sin getContext().
• Recuperación. Ramificar según el subtipo concreto. Véase NotYetImplementedException más abajo, el único subtipo distribuido en la entrega actual.

NotYetImplementedException

• Cuándo se lanza. Todo conformador de escritura de marcador de posición lanza esto desde su cuerpo shape() para las escrituras cuyo conformado concreto está diferido (mongol y tibetano). La costura del SPI de conformado está lista a nivel de arquitectura, pero el conformado real está pendiente de un dispositivo de prueba validado por hablantes nativos. Lanzar una excepción en lugar de una operación nula silenciosa aflora un cableado de producción accidental en tiempo de ejecución, en vez de emitir texto sin conformar a un PDF que afirma accesibilidad etiquetada.
• Datos transportados. Extiende ScriptShaperException (y, por tanto, RuntimeException), de modo que no es consciente del contexto y no tiene getContext(). Los datos de diagnóstico están en sus propiedades public readonly: bcp47LanguageTag (la etiqueta BCP-47 de la secuencia, como mn-Mong o bo-Tibt) y missingCapability (la capacidad concreta de la que carece la implementación). El mensaje incluye ambas.
• Recuperación. No encaminar en producción las secuencias en las escrituras no implementadas a través del conformador. Detectar la etiqueta de idioma aguas arriba y recurrir a una vía de representación distinta o fijar la versión a una futura entrega que incorpore el conformado para la escritura afectada.

Perfiles de salida del escritor y cifrado

Pdf14FeatureRejectedException

• Cuándo se lanza. El escritor lanza esto cuando un documento contiene una funcionalidad prohibida bajo el perfil de salida PDF 1.4 (ISO 19005-1:2005 / PDF/A-1), que prohíbe las construcciones introducidas en versiones posteriores de PDF.
• Datos transportados. Extiende NextPdfException pero no redefine getContext(), de modo que getContext() devuelve un arreglo vacío. Los datos de diagnóstico están en sus propiedades public readonly: feature (el nombre de la funcionalidad rechazada), reason (por qué está prohibida) e isoClause (la referencia de cláusula ISO). El mensaje combina las tres.
• Recuperación. Eliminar o sustituir la funcionalidad rechazada por un equivalente compatible con PDF 1.4, o apuntar a un perfil de salida superior que permita la funcionalidad.

Pdf20FeatureRejectedException

• Cuándo se lanza. El escritor lanza esto cuando un documento contiene una funcionalidad prohibida bajo el perfil de salida estricto de PDF 2.0. ISO 32000-2:2020 deja obsoletas construcciones que PDF 1.7 aún permitía —en particular las fuentes Standard 14 de Type 1 (§9.6.2), que deben incrustarse en un documento PDF 2.0 conforme.
• Datos transportados. Misma forma que Pdf14FeatureRejectedException: extiende NextPdfException, no redefine getContext() (devuelve un arreglo vacío) y expone feature, reason e isoClause como propiedades public readonly.
• Recuperación. Remediar la funcionalidad rechazada —por ejemplo, incrustar las 14 fuentes base— o tomar la vía de escape documentada cuando exista (para las 14 fuentes base no incrustadas, Document::allowNonEmbeddedBase14()).

PublicKeyEncryptionUnsupportedException

• Cuándo se lanza. PdfWriter::build() lanza esto en el punto de entrada cuando el encryptionMode del documento es pubkey (una lista de destinatarios de clave pública) antes de que esté cableado el despacho de cifrado del cuerpo de flujo de clave pública del lado del escritor. Negarse de antemano evita emitir de forma silenciosa un PDF sin cifrar que el llamador creía cifrado.
• Datos transportados. Extiende directamente RuntimeException, de modo que no es consciente del contexto y no tiene getContext(). Es un refinamiento estricto de la excepción genérica que el mismo punto lanzaba antes, de modo que los manejadores catch (\RuntimeException) existentes siguen funcionando.
• Recuperación. Usar un modo de cifrado compatible (cifrado basado en contraseña) en lugar de la lista de destinatarios de clave pública, o fijar la versión a una entrega que incorpore el soporte de cifrado de clave pública. No tratar la salida como cifrada cuando se lanza esto.

Entrada del lector y de metadatos

UnsupportedPdfStructureException

• Cuándo se lanza. El lector del grafo de objetos lanza esto, de forma cerrada, cuando un PDF de entrada queda fuera de su envoltura compatible. El lector admite tablas de referencias cruzadas clásicas (ISO 32000-2:2020 §7.5.4), flujos de referencias cruzadas (§7.5.8), objetos comprimidos en flujos de objetos (§7.5.7), cadenas /Prev de varias revisiones (§7.5.6) y archivos de referencia híbrida vía /XRefStm (§7.5.8.4). Cualquier cosa fuera de esa envoltura aflora esta excepción en lugar de un análisis parcial o adivinado. Los constructores con nombre se asignan a los casos de motivo: encrypted(), damagedCrossReference(), cyclicReferenceChain(), nonConformantObjectStream(), irresolvableObjectCollision(), truncatedFile() y crossReferenceOffsetOutOfBounds().
• Datos transportados. Extiende directamente RuntimeException, de modo que no es consciente del contexto y no tiene getContext(). Expone una propiedad public readonly reason de tipo UnsupportedPdfStructureReason (una enumeración) para que los llamadores ramifiquen según la categoría precisa sin analizar el mensaje; una cadena detail opcional y una previous lanzable pueden añadir contexto acotado y no sensible. El mensaje predeterminado es el resumen sin filtración del motivo.
• Recuperación. Ramificar según reason. Para EncryptedDocument, ejecutar un paso de descifrado antes de leer, ya que el descifrado queda fuera del alcance del lector. Para DamagedCrossReference, TruncatedFile o CrossReferenceOffsetOutOfBounds, tratar el archivo como malformado o incompleto y volver a adquirir o reparar el origen. Para CyclicReferenceChain, NonConformantObjectStream o IrresolvableObjectCollision, la entrada viola el modelo estructural y no se puede leer tal cual.

PacketTooLargeException

• Cuándo se lanza. El lector de metadatos XMP por flujo lanza esto cuando un paquete XMP incrustado supera el tope de bytes configurado. Es una protección defensiva contra entradas de estilo expansión de entidades y explosión cuadrática (un tope máximo de 128 MB frente a XMP incrustado de escala de gigabytes).
• Datos transportados. Extiende NextPdfException pero no redefine getContext(), de modo que getContext() devuelve un arreglo vacío. Los datos de diagnóstico están en sus propiedades public readonly: byteCount (el recuento de bytes observado) y cap (el tope configurado en bytes). El mensaje informa de ambos.
• Recuperación. Rechazar u omitir los metadatos sobredimensionados por maliciosos o malformados. Si un documento legítimo necesita realmente un paquete mayor, elevar el tope configurado de forma deliberada, sopesando el riesgo de agotamiento de memoria que la protección existe para prevenir.

Véase también

• Índice de la referencia de errores
• Resolución de problemas de fuentes y etiquetado — para los síntomas de NotYetImplementedException, ScriptShaperException e IcuRequirementException.
• Resolución de problemas de validación de PDF/A y PDF/UA — para los síntomas de Pdf14FeatureRejectedException y Pdf20FeatureRejectedException.
• Resolución de problemas de cifrado y permisos — para PublicKeyEncryptionUnsupportedException y el motivo EncryptedDocument del lector.