Filter — Referência Profunda

Visão geral

Esta página é a referência em nível de contrato do módulo Filter do NextPDF Pro, namespace NextPDF\Pro\Filter. A superfície consiste em duas classes. DecodeParms analisa um fragmento de dicionário /DecodeParms de PDF, convertendo-o em um objeto de valor imutável e com limites verificados. PngPredictor reverte a família de preditores PNG (tags 10-15) sobre bytes de fluxo decodificados por FlateDecode. O módulo atende aos extratores Diff e Classifier do Pro. Não é um framework geral de filtros de fluxo. Esta página descreve a API pública, o contrato de comportamento observável e os modos de falha tipados. Orientações de uso e exemplos de código estão na página de capacidade do Filter.

Disponibilidade e licenciamento

Esta capacidade é distribuída no NextPDF Pro (nextpdf/pro) e é ativada por um envelope de licença de nível Pro. Uma implantação sem esse direito de uso não carrega as classes da capacidade. Compare as edições e obtenha uma licença.

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

Superfície da API pública

Símbolo	Parâmetros	Comportamento padrão	Retorna	Lança ou falha com	Notas
DecodeParms	construtor: int $predictor = 1, int $columns = 1, int $colors = 1, int $bitsPerComponent = 8	Os padrões codificam “sem preditor”	—	—	final readonly; todas as quatro propriedades são públicas e imutáveis
DecodeParms::fromDictionary()	string $raw — texto bruto do dicionário, corpo do objeto ao redor é tolerado	Chaves ausentes mantêm seus padrões; a correspondência tolera espaços em branco	self	InvalidArgumentException	Ponto de estrangulamento em tempo de análise; limites listados no contrato de comportamento
DecodeParms::isPngPredictor()	nenhum	Predicado puro; sem I/O	bool — true para o preditor 10-15	—	Ramifique com base nisto antes de chamar o filtro reverso
PngPredictor	—	Sem estado	—	—	final; o único ponto de entrada é o inverse() estático
PngPredictor::inverse()	string $raw, int $columns, int $colors, int $bitsPerComponent, int $predictor	Filtra de forma reversa linha por linha com base na tag por linha; entrada vazia retorna uma string vazia	string — payload reconstruído com as tags de filtro removidas	InvalidArgumentException	Aceita apenas o preditor 10-15; o preditor TIFF está fora do escopo

Assinaturas dos pontos 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 comportamento

Análise de /DecodeParms

DecodeParms::fromDictionary() corresponde a quatro chaves reconhecidas como inteiros no texto bruto do dicionário: /Predictor, /Columns, /Colors e /BitsPerComponent. Esses são os parâmetros de preditor que a ISO 32000-2:2020 §7.4.4.4 define para os filtros LZWDecode e FlateDecode. A correspondência tolera espaços em branco e sobrevive a tokens PDF ao redor. Chaves ausentes mantêm seus padrões: preditor 1, columns 1, colors 1, bits-per-component 8. Os valores presentes são validados de forma fail-closed em tempo de análise, antes que qualquer geometria possa alcançar a alocação de linha do filtro reverso:

• Um valor negativo presente para qualquer chave reconhecida é rejeitado.
• /Columns acima de 1,000,000 é rejeitado.
• /Colors acima de 32 é rejeitado.
• /BitsPerComponent fora de {1, 2, 4, 8, 16} é rejeitado.
• Um stride de linha derivado acima de 64,000,000 bytes é rejeitado.

isPngPredictor() retorna true quando o preditor analisado está entre 10 e 15. O preditor 1 (sem predição) e o preditor 2 (o grupo TIFF) retornam false.

Geometria da linha

PngPredictor::inverse() consome um fluxo de bytes decodificado por FlateDecode em que cada linha é precedida por uma tag de filtro de um byte. Ele emite o payload reconstruído com as tags removidas. A largura do payload da linha é ceil(columns * colors * bitsPerComponent / 8) bytes; o stride da linha acrescenta um byte de tag. O deslocamento do vizinho à esquerda (bytes por pixel) é max(1, floor(colors * bitsPerComponent / 8)), de modo que empacotamentos sub-byte são arredondados para baixo até um byte. A filtragem opera sobre bytes inteiros independentemente da profundidade de bits, correspondendo à semântica de filtro do PNG.

Reconstrução por linha

Tag	Filtro	Reconstrução
0	None	passagem direta
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 as somas são tomadas módulo 256. Para a primeira linha, e para os bytes à esquerda do primeiro pixel, o vizinho ausente é lido como zero, conforme W3C PNG §9.2. A operação reversa é orientada inteiramente pela tag por linha. Esse é o comportamento conforme tanto para os preditores fixos (10-14) quanto para o Optimum (15) segundo a ISO 32000-2:2020 §7.4.4.4, portanto a variação de tag do escritor é tolerada.

Camadas de validação

A validação de parâmetros é executada em duas camadas por design. DecodeParms é o ponto de estrangulamento em tempo de análise e rejeita magnitudes hostis primeiro. PngPredictor::inverse() mantém suas próprias verificações como uma segunda camada: verificações de intervalo em todos os quatro parâmetros, proteções contra estouro que comparam fatores isolados com PHP_INT_MAX antes de formar o produto do stride, o mesmo teto por linha de 64,000,000 bytes e um limite proporcional à entrada que rejeita um stride declarado maior que a entrada inteira antes de qualquer buffer de linha ser alocado.

Determinismo

Ambos os pontos de entrada são funções estáticas puras de suas entradas. Não há I/O, nem registro em log, nem estado global. O tempo de execução é linear no comprimento da entrada com uma pequena constante por byte. A análise de /DecodeParms são algumas correspondências de expressão regular limitadas. Os orçamentos estão declarados no performance_budget do frontmatter.

Casos extremos e modos de falha

Toda falha neste módulo gera InvalidArgumentException com o valor problemático nomeado na mensagem.

• fromDictionary() rejeita um valor negativo presente para qualquer chave reconhecida.
• fromDictionary() rejeita /Columns acima de 1,000,000 e /Colors acima de 32.
• fromDictionary() rejeita /BitsPerComponent fora de {1, 2, 4, 8, 16} e um stride de linha derivado acima de 64,000,000 bytes.
• inverse() rejeita um preditor fora de 10-15. O preditor TIFF (2) nunca é filtrado de forma reversa aqui; ramifique com base em isPngPredictor() primeiro.
• inverse() rejeita columns ou colors abaixo de 1 e bitsPerComponent fora do conjunto legal.
• inverse() rejeita geometria cujo produto de stride estouraria o inteiro da plataforma, antes de qualquer alocação.
• inverse() rejeita um stride de linha acima do teto por linha de 64,000,000 bytes, independentemente do comprimento real da entrada.
• inverse() retorna uma string vazia para entrada vazia; isso não é um erro.
• inverse() falha um stride de linha declarado maior que a entrada inteira como uma linha truncada no deslocamento 0.
• inverse() falha uma linha parcial ao final como uma linha truncada, nomeando o deslocamento e as contagens de bytes.
• inverse() falha uma tag de filtro por linha desconhecida (que não seja 0-4) com o valor da tag e o deslocamento da linha.
• Uma incompatibilidade entre a geometria declarada em /DecodeParms e o layout real do fluxo se manifesta como um erro de parâmetro ou de truncamento, nunca como saída silenciosamente corrompida.
• O filtro Average usa divisão inteira, correspondendo à semântica de floor da especificação PNG.
• Nenhuma operação criptográfica ocorre neste módulo. O comportamento é idêntico em implantações restritas por FIPS.

Conformidade

Alegação	Padrão	Cláusula
O parâmetro de filtro /Predictor seleciona o algoritmo de preditor; os valores permitidos vêm da tabela de valores de preditor.	ISO 32000-2:2020	§7.4.4.4
O PDF define dois grupos de preditor: o grupo TIFF é a única função Predictor 2; o grupo PNG são as tags 10-15.	ISO 32000-2:2020	§7.4.4.4
Os valores válidos de /BitsPerComponent são 1, 2, 4, 8 e 16, com padrão 8; /Colors é 1 ou maior, com padrão 1; /Columns tem padrão 1.	ISO 32000-2:2020	§7.4.4.4
As funções de reconstrução para os tipos de filtro 0-4 operam byte a byte módulo 256; bytes ausentes à esquerda e da linha anterior são lidos como zero.	W3C PNG (Third Edition)	§9.2
O tipo de filtro Paeth calcula o PaethPredictor dos vizinhos à esquerda, acima e superior-esquerdo e escolhe o mais próximo.	W3C PNG (Third Edition)	§9.4

Todas as cláusulas são parafraseadas; o NextPDF não reproduz texto normativo. Estas são declarações de capacidade, não certificações; o NextPDF não possui nenhuma certificação e não concede nenhuma. A conformidade da matemática de reconstrução e dos padrões de parâmetro é exercitada pela suíte de testes unitários. Um framework completo de filtros de fluxo de PDF, e a reversão do preditor TIFF, estão fora do escopo deste módulo.

Notas de desenvolvimento

• Ambas as classes são distribuídas desde o nextpdf/pro 3.0.0 e estão atualizadas na 3.1.0.
• O módulo é consumido pelos extratores Diff e Classifier do Pro quando suas entradas carregam um preditor.
• Ramifique com base em isPngPredictor() antes de chamar inverse(); o preditor 1 e o preditor TIFF não precisam de reversão PNG.
• O módulo limita sua própria alocação por linha. Chamadores que revertem preditores em fluxos não confiáveis ainda devem limitar o tamanho da entrada descompactada a montante, como fazem os extratores do Pro.
• Os preditores fixos (10-14) e o Optimum (15) compartilham um único caminho de código; a tag por linha orienta a reconstrução em ambos os casos.
• Detalhes de mecanismo interno permanecem na documentação interna do repositório de origem e estão fora do escopo deste manual.

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 mecanismo, nomes de arquivo de runbook e prefixos de ticket estão fora do escopo.

Veja também

• Filter (capacidade) — instalação, início rápido e exemplos de uso em produção.
• Diff — Referência Profunda — um consumidor do filtro reverso.
• Classifier — Referência Profunda — um consumidor do filtro reverso.