Filtro

In breve

NextPDF\Pro\Filter fornisce due helper mirati: un parser per il dizionario PDF /DecodeParms e un reverse-filter per il predittore PNG applicato agli stream FlateDecode. È il supporto al predittore usato dagli estrattori Diff e Classifier di Pro; non è un framework generale di filtri.

Disponibilità e licenze

Questa funzionalità è distribuita in NextPDF Pro (nextpdf/pro) e si attiva con un envelope di licenza di livello Pro. Un deployment privo di tale entitlement non carica le classi della funzionalità. Confronta le edizioni e ottieni una licenza.

Le classi del Filter sono disponibili ogni volta che nextpdf/pro è installato; nessun flag di capacità a runtime governa questo modulo.

Installazione

composer require nextpdf/pro:^3

Panoramica concettuale

Gli stream PDF possono essere compressi con FlateDecode e inoltre pre-elaborati con un predittore per migliorare la compressione. ISO 32000-2:2020 §7.4.4.4 definisce i parametri del predittore (/Predictor, /Columns, /Colors, /BitsPerComponent) e la famiglia del predittore PNG (tag 10–15).

• DecodeParms analizza un frammento di dizionario /DecodeParms in un value object immutabile con default ragionevoli (predittore 1, colonne 1, colori 1, bit-per-componente 8). isPngPredictor() è vero per i tag 10–15.
• PngPredictor applica l’inverso dei cinque tipi di filtro PNG — None, Sub, Up, Average, Paeth — oltre a Optimum (predittore 15, tag per riga). Convalida i parametri e solleva InvalidArgumentException su valori fuori intervallo o su una riga troncata.

Questo modulo inverte un predittore esistente durante la lettura di uno stream. Non implementa l’insieme completo dei filtri di stream PDF e non fornisce hook di ottimizzazione dei filtri.

Perché funziona così

Il modulo inverte un predittore esistente anziché offrire un framework generale di filtri. Gli estrattori Diff e Classifier di Pro leggono soltanto ciò che un produttore ha già scritto, quindi un ambito ristretto è sufficiente. Tale ambito consente di delimitare ogni input prima di elaborare un solo byte. DecodeParms::fromDictionary() è il punto di strozzatura in fase di parsing: rifiuta geometrie negative o sovradimensionate e applica i default di DecodeParms::__construct() dove una chiave è assente. PngPredictor ri-verifica quei limiti in fase di applicazione, così che un /DecodeParms ostile sollevi un errore tipizzato anziché una grande allocazione. I chiamanti diramano su DecodeParms::isPngPredictor(), tenendo il predittore TIFF fuori da un reverse filter che gestisce solo i tag 10–15.

Contesto di progettazione: Stream e filtri.

Contratto di comportamento

• DecodeParms::fromDictionary(string $raw): self — corrispondenza degli interi tollerante agli spazi bianchi; le chiavi assenti mantengono i propri default.
• PngPredictor::inverse(string $raw, int $columns, int $colors, int $bitsPerComponent, int $predictor): string — il predittore deve essere 10–15; colonne e colori devono essere ≥ 1; i bit-per-componente devono essere 1, 2, 4, 8 o 16; una riga più corta dello stride calcolato solleva InvalidArgumentException.
• Determinismo. L’output è una funzione pura degli input.

Superficie API pubblica

Type	Kind	Key members
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

Esempio di codice — Avvio rapido

<?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,
    );
}

Esempio di codice — Produzione

<?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
    }
}

Casi limite e insidie

• Il predittore TIFF (tag 2) è riconosciuto da DecodeParms ma non è soggetto a reverse-filter da PngPredictor (che accetta solo 10–15). I chiamanti dovrebbero diramarsi su isPngPredictor().
• Una riga del predittore più corta dello stride calcolato viene rifiutata; non viene troncata silenziosamente.
• Lo stride della riga è calcolato da columns * colors * bitsPerComponent; un /DecodeParms non corrispondente al layout effettivo dello stream produce un errore di parametro o di troncamento anziché un output corrotto.

Prestazioni

PngPredictor::inverse() è lineare rispetto alla lunghezza dello stream con una piccola costante per byte. L’analisi di DecodeParms consiste in alcune corrispondenze di espressioni regolari delimitate. Vedere performance_budget.

Note di sicurezza

Gli intervalli dei parametri vengono convalidati prima di qualunque elaborazione di byte, e una riga troncata solleva un’eccezione anziché leggere fuori dai limiti. I chiamanti che invertono predittori su stream non attendibili dovrebbero inoltre delimitare a monte la dimensione decompressa, come fanno gli estrattori Diff e Classifier di Pro.

Conformità

Claim	Spec clause	Status
/DecodeParms parameters and defaults	ISO 32000-2:2020 §7.4.4.4	Verified (unit suite)
PNG predictor reverse-filter, tags 10–15	ISO 32000-2:2020 §7.4.4.4	Verified (unit suite)
Full PDF stream-filter framework	—	Not supported (out of scope)

Fallback / alternativa Core

Non viene esposto alcun equivalente Core per l’inversione del predittore PNG. La gestione degli stream del Core è interna al motore e non fa parte di questa superficie pubblica.

Nota sul confine Enterprise

Questo è un helper di predittore ristretto. Non è un filtro crittografico, un sanificatore di contenuto o un componente di ricostruzione/disinnesco dei dati; tali temi sono fuori ambito.

Confine di pubblicazione

Questa pagina documenta solo il comportamento osservabile dall’esterno e la superficie API pubblica supportata. I percorsi di namespace interni, le classi helper, le tabelle dei meccanismi, i nomi dei file di runbook e i prefissi dei ticket sono fuori ambito.

Vedere anche

• Riferimento Filter
• Diff
• Classifier
• Specifiche PDF 2.0