Pro edición

Filter

De un vistazo

NextPDF\Pro\Filter proporciona dos ayudantes específicos: un analizador para el diccionario /DecodeParms de PDF y un filtro inverso para el predictor PNG aplicado a los flujos con FlateDecode. Es el soporte de predictor que usan los extractores Diff y Classifier de Pro; no es un marco de filtros general.

Disponibilidad y licencias

Esta capacidad se incluye en NextPDF Pro (nextpdf/pro) y se activa con un sobre de licencia de nivel Pro. Un despliegue sin esa titularidad no carga las clases de la capacidad. Compare ediciones y obtenga una licencia.

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

Instalación

composer require nextpdf/pro:^3

Descripción conceptual

Los flujos PDF pueden estar comprimidos con FlateDecode y, además, preprocesados con un predictor para mejorar la compresión. ISO 32000-2:2020 §7.4.4.4 define los parámetros del predictor (/Predictor, /Columns, /Colors, /BitsPerComponent) y la familia de predictores PNG (etiquetas 10–15).

DecodeParms analiza un fragmento de diccionario /DecodeParms en un objeto de valor inmutable con valores predeterminados razonables (predictor 1, columns 1, colors 1, bits-per-component 8). isPngPredictor() es verdadero para las etiquetas 10–15.
PngPredictor aplica la inversa de los cinco tipos de filtro PNG — None, Sub, Up, Average, Paeth — más Optimum (predictor 15, etiqueta por fila). Valida los parámetros y genera InvalidArgumentException ante valores fuera de rango o una fila truncada.

Este módulo invierte un predictor existente al leer un flujo. No implementa el conjunto completo de filtros de flujo PDF y no proporciona ganchos de ajuste de filtros.

Por qué funciona así

El módulo invierte un predictor existente en lugar de ofrecer un marco de filtros general. Los extractores Diff y Classifier de Pro solo leen lo que un productor ya escribió, por lo que un alcance estrecho basta. Ese alcance permite acotar cada entrada antes de procesar un solo byte. DecodeParms::fromDictionary() es el punto de estrangulamiento en tiempo de análisis: rechaza geometrías negativas o sobredimensionadas y aplica los valores predeterminados de DecodeParms::__construct() donde falta una clave. PngPredictor vuelve a comprobar esos límites en tiempo de aplicación, de modo que un /DecodeParms hostil genera un error tipado en lugar de una gran asignación. Los llamantes ramifican según DecodeParms::isPngPredictor(), manteniendo el predictor TIFF fuera de un filtro inverso que solo maneja las etiquetas 10–15.

Contexto de diseño: Flujos y filtros.

Contrato de comportamiento

DecodeParms::fromDictionary(string $raw): self — coincidencia de enteros tolerante a espacios en blanco; las claves ausentes conservan sus valores predeterminados.
PngPredictor::inverse(string $raw, int $columns, int $colors, int $bitsPerComponent, int $predictor): string — el predictor debe ser 10–15; columns y colors deben ser ≥ 1; bits-per-component debe ser 1, 2, 4, 8 o 16; una fila más corta que el paso (stride) calculado genera InvalidArgumentException.
Determinismo. La salida es una función pura de las entradas.

Superficie pública de la API

Tipo	Clase	Miembros clave
`NextPDF\Pro\Filter\DecodeParms`	`final readonly class`	`__construct(int $predictor = 1, int $columns = 1, int $colors = 1, int $bitsPerComponent = 8)`, `static fromDictionary(string $raw): self`, `isPngPredictor(): bool`
`NextPDF\Pro\Filter\PngPredictor`	`final class`	`static inverse(string $raw, int $columns, int $colors, int $bitsPerComponent, int $predictor): string`

Ejemplo de código — Inicio rápido

<?php

declare(strict_types=1);

use NextPDF\Pro\Filter\DecodeParms;
use NextPDF\Pro\Filter\PngPredictor;

$parms = DecodeParms::fromDictionary('<< /Predictor 15 /Columns 640 /Colors 3 >>');

if ($parms->isPngPredictor()) {
    $raw = PngPredictor::inverse(
        $flateDecodedBytes,
        $parms->columns,
        $parms->colors,
        $parms->bitsPerComponent,
        $parms->predictor,
    );
}

Ejemplo de código — Producción

<?php

declare(strict_types=1);

use InvalidArgumentException;
use NextPDF\Pro\Filter\DecodeParms;
use NextPDF\Pro\Filter\PngPredictor;

function undoPredictor(string $decoded, string $dictFragment): string
{
    $parms = DecodeParms::fromDictionary($dictFragment);

    if (! $parms->isPngPredictor()) {
        return $decoded; // no predictor, or TIFF predictor — return as-is
    }

    try {
        return PngPredictor::inverse(
            $decoded,
            $parms->columns,
            $parms->colors,
            $parms->bitsPerComponent,
            $parms->predictor,
        );
    } catch (InvalidArgumentException) {
        return $decoded; // malformed predictor metadata — fail safe
    }
}

Casos límite y trampas

El predictor TIFF (etiqueta 2) es reconocido por DecodeParms, pero no lo filtra de forma inversa PngPredictor (que solo acepta 10–15). Los llamantes deben ramificar según isPngPredictor().
Una fila de predictor más corta que el paso calculado se rechaza; no se trunca de forma silenciosa.
El paso de fila se calcula a partir de columns * colors * bitsPerComponent; un /DecodeParms que no coincide con la disposición real del flujo produce un error de parámetro o de truncamiento en lugar de una salida corrupta.

Rendimiento

PngPredictor::inverse() es lineal respecto a la longitud del flujo con una pequeña constante por byte. El análisis de DecodeParms consiste en unas pocas coincidencias de expresiones regulares acotadas. Consulte performance_budget.

Notas de seguridad

Los rangos de parámetros se validan antes de cualquier procesamiento de bytes, y una fila truncada genera una excepción en lugar de leer fuera de los límites. Los llamantes que invierten predictores en flujos no confiables también deben acotar el tamaño descomprimido aguas arriba, como hacen los extractores Diff y Classifier de Pro.

Conformidad

Declaración	Cláusula del estándar	Estado
Parámetros y valores predeterminados de `/DecodeParms`	ISO 32000-2:2020 §7.4.4.4	Verificado (conjunto unitario)
Filtro inverso del predictor PNG, etiquetas 10–15	ISO 32000-2:2020 §7.4.4.4	Verificado (conjunto unitario)
Marco completo de filtros de flujo PDF	—	No admitido (fuera del alcance)

Alternativa / respaldo de Core

No se expone ningún equivalente en Core para la inversión del predictor PNG. El tratamiento de flujos propio de Core es interno al motor y no forma parte de esta superficie pública.

Nota sobre el límite de Enterprise

Es un ayudante de predictor estrecho. No es un filtro criptográfico, un saneador de contenido, ni un componente de reconstrucción/desarme de datos; esas cuestiones quedan fuera del alcance.

Límite de publicación

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