Filter — Referencia detallada

De un vistazo

Esta página es la referencia a nivel de contrato del módulo Filter de NextPDF Pro, espacio de nombres NextPDF\Pro\Filter. La superficie consta de dos clases. DecodeParms analiza un fragmento de diccionario /DecodeParms de PDF y lo convierte en un objeto de valor inmutable y con límites verificados. PngPredictor invierte la familia de predictores PNG (etiquetas 10-15) sobre bytes de flujo con FlateDecode. El módulo da servicio a los extractores Diff y Classifier de Pro. No es un marco de trabajo general de filtros de flujo. Esta página expone la API pública, el contrato de comportamiento observable y los modos de fallo tipados. La guía de uso y los ejemplos de código están en la página de capacidad de Filter.

Disponibilidad y licencias

Esta capacidad se distribuye en NextPDF Pro (nextpdf/pro) y se activa con un envoltorio de licencia de nivel Pro. Un despliegue sin ese derecho no carga las clases de la capacidad. Comparar ediciones y obtener una licencia.

Ningún indicador de capacidad en tiempo de ejecución restringe este módulo. Las clases de Filter están disponibles siempre que nextpdf/pro esté instalado.

Superficie de la API pública

Símbolo	Parámetros	Comportamiento por defecto	Devuelve	Lanza o falla con	Notas
DecodeParms	constructor: int $predictor = 1, int $columns = 1, int $colors = 1, int $bitsPerComponent = 8	Los valores por defecto codifican «sin predictor»	—	—	final readonly; las cuatro propiedades son públicas e inmutables
DecodeParms::fromDictionary()	string $raw — texto de diccionario en bruto, se tolera el cuerpo de objeto circundante	Las claves ausentes conservan sus valores por defecto; la coincidencia tolera espacios en blanco	self	InvalidArgumentException	Punto de estrangulamiento en tiempo de análisis; los límites figuran en el contrato de comportamiento
DecodeParms::isPngPredictor()	ninguno	Predicado puro; sin E/S	bool — true para predictor 10-15	—	Ramifique según esto antes de llamar al filtro inverso
PngPredictor	—	Sin estado	—	—	final; el único punto de entrada es el estático inverse()
PngPredictor::inverse()	string $raw, int $columns, int $colors, int $bitsPerComponent, int $predictor	Aplica el filtro inverso fila a fila según la etiqueta de cada fila; una entrada vacía devuelve una cadena vacía	string — carga útil reconstruida con las etiquetas de filtro eliminadas	InvalidArgumentException	Acepta únicamente predictor 10-15; el predictor TIFF queda fuera de alcance

Firmas de los puntos de entrada

public function __construct(
    public int $predictor = 1,
    public int $columns = 1,
    public int $colors = 1,
    public int $bitsPerComponent = 8,
) {}

public static function fromDictionary(string $raw): self

public function isPngPredictor(): bool

public static function inverse(
    string $raw,
    int $columns,
    int $colors,
    int $bitsPerComponent,
    int $predictor,
): string

Contrato de comportamiento

Análisis de /DecodeParms

DecodeParms::fromDictionary() reconoce como enteros cuatro claves en el texto de diccionario en bruto: /Predictor, /Columns, /Colors y /BitsPerComponent. Son los parámetros de predictor que ISO 32000-2:2020 §7.4.4.4 define para los filtros LZWDecode y FlateDecode. La coincidencia tolera espacios en blanco y sobrevive a los tokens PDF circundantes. Las claves ausentes conservan sus valores por defecto: predictor 1, columnas 1, colores 1, bits por componente 8. Los valores presentes se validan de forma cerrada por defecto en tiempo de análisis, antes de que cualquier geometría pueda llegar a la asignación de filas del filtro inverso:

• Se rechaza un valor negativo presente para cualquier clave reconocida.
• Se rechaza /Columns por encima de 1.000.000.
• Se rechaza /Colors por encima de 32.
• Se rechaza /BitsPerComponent fuera de {1, 2, 4, 8, 16}.
• Se rechaza un paso de fila derivado por encima de 64.000.000 de bytes.

isPngPredictor() devuelve true cuando el predictor analizado está entre 10 y 15. El predictor 1 (sin predicción) y el predictor 2 (el grupo TIFF) devuelven false.

Geometría de fila

PngPredictor::inverse() consume un flujo de bytes con FlateDecode en el que cada fila va precedida por una etiqueta de filtro de un byte. Emite la carga útil reconstruida con las etiquetas eliminadas. El ancho de la carga útil de fila es ceil(columns * colors * bitsPerComponent / 8) bytes; el paso de fila añade un byte de etiqueta. El desplazamiento del vecino izquierdo (bytes por píxel) es max(1, floor(colors * bitsPerComponent / 8)), de modo que los empaquetados de sub-byte quedan reducidos a un byte. El filtrado opera sobre bytes completos con independencia de la profundidad de bits, conforme a la semántica de filtros PNG.

Reconstrucción por fila

Etiqueta	Filtro	Reconstrucción
0	None	paso directo
1	Sub	recon[x] = filt[x] + recon[x-bpp]
2	Up	recon[x] = filt[x] + prior[x]
3	Average	recon[x] = filt[x] + floor((recon[x-bpp] + prior[x]) / 2)
4	Paeth	recon[x] = filt[x] + Paeth(left, up, up-left)

Todas las sumas se toman módulo 256. Para la primera fila, y para los bytes situados a la izquierda del primer píxel, el vecino ausente se lee como cero, según W3C PNG §9.2. La operación inversa está regida por completo por la etiqueta de cada fila. Ese es el comportamiento conforme tanto para los predictores fijos (10-14) como para Optimum (15) bajo ISO 32000-2:2020 §7.4.4.4, de modo que se tolera la variación de etiquetas del escritor.

Estratificación de la validación

La validación de parámetros se ejecuta en dos capas por diseño. DecodeParms es el punto de estrangulamiento en tiempo de análisis y rechaza primero las magnitudes hostiles. PngPredictor::inverse() mantiene sus propias comprobaciones como segunda capa: comprobaciones de rango sobre los cuatro parámetros, protecciones frente a desbordamiento que comparan factores individuales con PHP_INT_MAX antes de formar el producto del paso, el mismo límite máximo de 64.000.000 de bytes por fila, y un límite proporcional a la entrada que rechaza un paso declarado mayor que la entrada completa antes de asignar cualquier búfer de fila.

Determinismo

Ambos puntos de entrada son funciones estáticas puras de sus entradas. No hay E/S, ni registro, ni estado global. El tiempo de ejecución es lineal respecto a la longitud de la entrada con una pequeña constante por byte. El análisis de /DecodeParms consiste en unas pocas coincidencias acotadas de expresiones regulares. Los presupuestos figuran en el performance_budget del frontmatter.

Casos límite y modos de fallo

Todo fallo en este módulo lanza InvalidArgumentException con el valor infractor nombrado en el mensaje.

• fromDictionary() rechaza un valor negativo presente para cualquier clave reconocida.
• fromDictionary() rechaza /Columns por encima de 1.000.000 y /Colors por encima de 32.
• fromDictionary() rechaza /BitsPerComponent fuera de {1, 2, 4, 8, 16} y un paso de fila derivado por encima de 64.000.000 de bytes.
• inverse() rechaza un predictor fuera de 10-15. El predictor TIFF (2) nunca se filtra a la inversa aquí; ramifique primero según isPngPredictor().
• inverse() rechaza columns o colors por debajo de 1 y bitsPerComponent fuera del conjunto legal.
• inverse() rechaza una geometría cuyo producto de paso desbordaría el entero de la plataforma, antes de cualquier asignación.
• inverse() rechaza un paso de fila por encima del máximo de 64.000.000 de bytes por fila, con independencia de la longitud real de la entrada.
• inverse() devuelve una cadena vacía para una entrada vacía; eso no es un error.
• inverse() falla un paso de fila declarado mayor que la entrada completa como una fila truncada en el desplazamiento 0.
• inverse() falla una fila parcial final como una fila truncada, nombrando el desplazamiento y los recuentos de bytes.
• inverse() falla una etiqueta de filtro por fila desconocida (distinta de 0-4) con el valor de la etiqueta y el desplazamiento de la fila.
• Un desajuste entre la geometría declarada de /DecodeParms y la disposición real del flujo se manifiesta como un error de parámetro o de truncamiento, nunca como una salida corrupta de forma silenciosa.
• El filtro Average usa división entera, conforme a la semántica de suelo de la especificación PNG.
• No ocurre ninguna operación criptográfica en este módulo. El comportamiento es idéntico en despliegues restringidos por FIPS.

Conformidad

Afirmación	Norma	Cláusula
El parámetro de filtro /Predictor selecciona el algoritmo de predictor; los valores permitidos provienen de la tabla de valores de predictor.	ISO 32000-2:2020	§7.4.4.4
PDF define dos grupos de predictor: el grupo TIFF es la única función Predictor 2; el grupo PNG son las etiquetas 10-15.	ISO 32000-2:2020	§7.4.4.4
Los valores válidos de /BitsPerComponent son 1, 2, 4, 8 y 16 con valor por defecto 8; /Colors es 1 o mayor con valor por defecto 1; /Columns tiene valor por defecto 1.	ISO 32000-2:2020	§7.4.4.4
Las funciones de reconstrucción para los tipos de filtro 0-4 operan byte a byte módulo 256; los bytes izquierdos y de fila previa ausentes se leen como cero.	W3C PNG (Third Edition)	§9.2
El tipo de filtro Paeth calcula el PaethPredictor de los vecinos izquierdo, superior y superior-izquierdo y elige el más cercano.	W3C PNG (Third Edition)	§9.4

Todas las cláusulas están parafraseadas; NextPDF no reproduce texto normativo. Son declaraciones de capacidad, no certificaciones; NextPDF no posee certificación alguna ni la otorga. La conformidad del cálculo de reconstrucción y de los valores por defecto de los parámetros se ejercita mediante la suite de pruebas unitarias. Un marco de trabajo completo de filtros de flujo PDF, y la inversión del predictor TIFF, quedan fuera del alcance de este módulo.

Notas de desarrollo

• Ambas clases se distribuyen desde nextpdf/pro 3.0.0 y están vigentes en 3.1.0.
• El módulo es consumido por los extractores Diff y Classifier de Pro cuando sus entradas incluyen un predictor.
• Ramifique según isPngPredictor() antes de llamar a inverse(); el predictor 1 y el predictor TIFF no necesitan inversión PNG.
• El módulo acota su propia asignación por fila. Los llamadores que inviertan predictores sobre flujos no confiables deberían acotar aun así el tamaño de la entrada descomprimida aguas arriba, como hacen los extractores de Pro.
• Los predictores fijos (10-14) y Optimum (15) comparten una única ruta de código; la etiqueta de cada fila rige la reconstrucción en ambos casos.
• El detalle interno del mecanismo permanece en la documentación interna del repositorio de origen y queda fuera del alcance de este manual.

Límite de publicación

Esta página documenta únicamente el comportamiento observable externamente y la superficie de API pública admitida. Las rutas internas de espacios de nombres, las clases auxiliares, las tablas de mecanismos, los nombres de archivo de runbook y los prefijos de tickets quedan fuera de alcance.

Véase también

• Filter (capacidad) — instalación, inicio rápido y ejemplos de uso en producción.
• Diff — Referencia detallada — un consumidor del filtro inverso.
• Classifier — Referencia detallada — un consumidor del filtro inverso.