Pro edição

Filtro

Visão geral

NextPDF\Pro\Filter fornece dois helpers focados: um analisador para o dicionário PDF /DecodeParms e um filtro reverso para o preditor PNG aplicado a streams com FlateDecode. É o suporte a preditores usado pelos extratores Diff e Classifier do Pro; não é um framework de filtros geral.

Disponibilidade e licenciamento

Este recurso vem no NextPDF Pro (nextpdf/pro) e é ativado com um envelope de licença de nível Pro. Uma implantação sem essa titularidade não carrega as classes do recurso. Compare edições e obtenha uma licença.

As classes do Filter estão disponíveis sempre que nextpdf/pro está instalado; nenhum sinalizador de capacidade em tempo de execução restringe este módulo.

Instalação

composer require nextpdf/pro:^3

Visão conceitual

Streams PDF podem ser comprimidos com FlateDecode e, adicionalmente, pré-processados com um preditor para melhorar a compressão. A ISO 32000-2:2020 §7.4.4.4 define os parâmetros do preditor (/Predictor, /Columns, /Colors, /BitsPerComponent) e a família de preditores PNG (tags 10–15).

DecodeParms analisa um fragmento de dicionário /DecodeParms em um objeto de valor imutável com padrões sensatos (predictor 1, columns 1, colors 1, bits-per-component 8). isPngPredictor() é verdadeiro para as tags 10–15.
PngPredictor aplica o inverso dos cinco tipos de filtro PNG — None, Sub, Up, Average, Paeth — mais Optimum (predictor 15, tag por linha). Ele valida os parâmetros e lança InvalidArgumentException em valores fora do intervalo ou em uma linha truncada.

Este módulo reverte um preditor existente ao ler um stream. Ele não implementa o conjunto completo de filtros de stream do PDF e não fornece ganchos de ajuste de filtro.

Por que funciona assim

O módulo reverte um preditor existente em vez de oferecer um framework de filtros geral. Os extratores Diff e Classifier do Pro apenas leem o que um produtor já escreveu, portanto um escopo restrito é suficiente. Esse escopo permite que cada entrada seja limitada antes que qualquer byte seja processado. DecodeParms::fromDictionary() é o ponto de estrangulamento em tempo de análise: ele rejeita geometria negativa ou grande demais e aplica os padrões de DecodeParms::__construct() onde uma chave está ausente. PngPredictor reverifica esses limites no momento da aplicação, de modo que um /DecodeParms hostil lança um erro tipado em vez de uma grande alocação. Os chamadores ramificam com base em DecodeParms::isPngPredictor(), mantendo o preditor TIFF fora de um filtro reverso que trata apenas das tags 10–15.

Contexto de projeto: Streams e filtros.

Contrato de comportamento

DecodeParms::fromDictionary(string $raw): self — correspondência de inteiros tolerante a espaços em branco; chaves ausentes mantêm seus padrões.
PngPredictor::inverse(string $raw, int $columns, int $colors, int $bitsPerComponent, int $predictor): string — o predictor deve ser 10–15; columns e colors devem ser ≥ 1; bits-per-component deve ser 1, 2, 4, 8 ou 16; uma linha mais curta que o stride calculado lança InvalidArgumentException.
Determinismo. A saída é uma função pura das entradas.

Superfície pública da API

Tipo	Categoria	Membros principais
`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`

Exemplo de código — Início 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,
    );
}

Exemplo de código — Produção

<?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 extremos e armadilhas

O preditor TIFF (tag 2) é reconhecido por DecodeParms, mas não é revertido por PngPredictor (que aceita apenas 10–15). Os chamadores devem ramificar com base em isPngPredictor().
Uma linha de preditor mais curta que o stride calculado é rejeitada; ela não é truncada silenciosamente.
O stride da linha é calculado a partir de columns * colors * bitsPerComponent; um /DecodeParms incompatível com o layout real do stream produz um erro de parâmetro ou de truncamento em vez de saída corrompida.

Desempenho

PngPredictor::inverse() é linear no comprimento do stream com uma pequena constante por byte. A análise de DecodeParms é feita com algumas poucas correspondências de expressão regular limitadas. Consulte performance_budget.

Notas de segurança

Os intervalos de parâmetros são validados antes de qualquer processamento de bytes, e uma linha truncada lança uma exceção em vez de ler fora dos limites. Os chamadores que revertem preditores em streams não confiáveis também devem limitar o tamanho descomprimido a montante, como fazem os extratores Diff e Classifier do Pro.

Conformidade

Afirmação	Cláusula da spec	Status
Parâmetros e padrões de `/DecodeParms`	ISO 32000-2:2020 §7.4.4.4	Verificado (conjunto de testes unitários)
Filtro reverso de preditor PNG, tags 10–15	ISO 32000-2:2020 §7.4.4.4	Verificado (conjunto de testes unitários)
Framework completo de filtros de stream do PDF	—	Não suportado (fora de escopo)

Fallback / alternativa do Core

Nenhum equivalente do Core é exposto para a reversão do preditor PNG. O próprio tratamento de streams do Core é interno ao mecanismo e não faz parte desta superfície pública.

Nota sobre o limite do Enterprise

Este é um helper de preditor restrito. Ele não é um filtro criptográfico, um higienizador de conteúdo nem um componente de reconstrução/neutralização de dados; essas preocupações estão fora de escopo.

Limite de publicação

Esta página documenta apenas o comportamento observável externamente e a superfície pública de API suportada. Caminhos de namespace internos, classes auxiliares, tabelas de mecanismos, nomes de arquivos de runbook e prefixos de tickets estão fora de escopo.