Filter — Riferimento approfondito

In breve

Questa pagina è il riferimento a livello di contratto per il modulo Filter di NextPDF Pro, namespace NextPDF\Pro\Filter. La superficie è costituita da due classi. DecodeParms analizza un frammento di dizionario /DecodeParms PDF trasformandolo in un value object immutabile e con controllo dei limiti. PngPredictor inverte la famiglia di predittori PNG (tag 10-15) sui byte di stream decodificati con FlateDecode. Il modulo serve gli estrattori Diff e Classifier di Pro. Non è un framework generico per filtri di stream. Questa pagina enuncia l’API pubblica, il contratto di comportamento osservabile e le modalità di errore tipizzate. Le indicazioni d’uso e gli esempi di codice si trovano nella pagina della funzionalità Filter.

Disponibilità e licenza

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.

Nessun flag di capacità a runtime applica un gate a questo modulo. Le classi Filter sono disponibili ogni volta che nextpdf/pro è installato.

Superficie API pubblica

Simbolo	Parametri	Comportamento predefinito	Restituisce	Solleva o fallisce con	Note
DecodeParms	costruttore: int $predictor = 1, int $columns = 1, int $colors = 1, int $bitsPerComponent = 8	I valori predefiniti codificano “nessun predittore”	—	—	final readonly; tutte e quattro le proprietà sono pubbliche e immutabili
DecodeParms::fromDictionary()	string $raw — testo grezzo del dizionario, il corpo dell’oggetto circostante è tollerato	Le chiavi assenti mantengono i valori predefiniti; il matching tollera gli spazi	self	InvalidArgumentException	Punto di strozzatura in fase di analisi; i limiti sono elencati nel contratto di comportamento
DecodeParms::isPngPredictor()	nessuno	Predicato puro; nessun I/O	bool — true per i predittori 10-15	—	Effettuare la diramazione su questo prima di chiamare il filtro inverso
PngPredictor	—	Senza stato	—	—	final; l’unico punto di ingresso è il metodo statico inverse()
PngPredictor::inverse()	string $raw, int $columns, int $colors, int $bitsPerComponent, int $predictor	Applica il filtro inverso riga per riga in base al tag della singola riga; un input vuoto restituisce una stringa vuota	string — payload ricostruito con i tag di filtro rimossi	InvalidArgumentException	Accetta solo i predittori 10-15; il predittore TIFF è fuori ambito

Firme dei punti di ingresso

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

Contratto di comportamento

Analisi di /DecodeParms

DecodeParms::fromDictionary() riconosce quattro chiavi come interi nel testo grezzo del dizionario: /Predictor, /Columns, /Colors e /BitsPerComponent. Sono i parametri del predittore che ISO 32000-2:2020 §7.4.4.4 definisce per i filtri LZWDecode e FlateDecode. Il matching tollera gli spazi e sopravvive ai token PDF circostanti. Le chiavi assenti mantengono i valori predefiniti: predittore 1, columns 1, colors 1, bits-per-component 8. I valori presenti sono convalidati in modalità fail-closed in fase di analisi, prima che qualsiasi geometria possa raggiungere l’allocazione delle righe del filtro inverso:

• Un valore negativo presente per qualsiasi chiave riconosciuta viene rifiutato.
• /Columns superiore a 1,000,000 viene rifiutato.
• /Colors superiore a 32 viene rifiutato.
• /BitsPerComponent al di fuori di {1, 2, 4, 8, 16} viene rifiutato.
• Uno stride di riga derivato superiore a 64,000,000 byte viene rifiutato.

isPngPredictor() restituisce true quando il predittore analizzato è compreso tra 10 e 15. Il predittore 1 (nessuna predizione) e il predittore 2 (il gruppo TIFF) restituiscono false.

Geometria delle righe

PngPredictor::inverse() consuma uno stream di byte decodificato con FlateDecode in cui ciascuna riga è preceduta da un tag di filtro di un byte. Emette il payload ricostruito con i tag rimossi. La larghezza del payload di riga è di ceil(columns * colors * bitsPerComponent / 8) byte; lo stride di riga aggiunge un byte di tag. L’offset del vicino di sinistra (byte per pixel) è max(1, floor(colors * bitsPerComponent / 8)), quindi i packing sub-byte vengono arrotondati per difetto a un byte. Il filtraggio opera su byte interi indipendentemente dalla profondità di bit, in linea con la semantica dei filtri PNG.

Ricostruzione per riga

Tag	Filter	Ricostruzione
0	None	passthrough
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)

Tutte le somme sono prese modulo 256. Per la prima riga, e per i byte a sinistra del primo pixel, il vicino mancante è letto come zero, secondo W3C PNG §9.2. L’operazione inversa è guidata interamente dal tag per riga. Questo è il comportamento conforme sia per i predittori fissi (10-14) sia per Optimum (15) secondo ISO 32000-2:2020 §7.4.4.4, quindi la variazione dei tag tra writer è tollerata.

Stratificazione della convalida

La convalida dei parametri opera su due livelli per scelta progettuale. DecodeParms è il punto di strozzatura in fase di analisi e rifiuta per primo le magnitudini ostili. PngPredictor::inverse() mantiene i propri controlli come secondo livello: verifiche di intervallo su tutti e quattro i parametri, guardie di overflow che confrontano i singoli fattori con PHP_INT_MAX prima di formare il prodotto dello stride, lo stesso limite massimo per riga di 64,000,000 byte e un limite proporzionale all’input che rifiuta uno stride dichiarato più grande dell’intero input prima che venga allocato qualsiasi buffer di riga.

Determinismo

Entrambi i punti di ingresso sono funzioni statiche pure dei loro input. Non c’è I/O, né logging, né stato globale. Il tempo di esecuzione è lineare rispetto alla lunghezza dell’input con una piccola costante per byte. L’analisi di /DecodeParms consiste in poche corrispondenze di espressioni regolari limitate. I budget sono indicati nel campo performance_budget del frontmatter.

Casi limite e modalità di errore

Ogni errore in questo modulo solleva InvalidArgumentException con il valore incriminato indicato nel messaggio.

• fromDictionary() rifiuta un valore negativo presente per qualsiasi chiave riconosciuta.
• fromDictionary() rifiuta /Columns superiore a 1,000,000 e /Colors superiore a 32.
• fromDictionary() rifiuta /BitsPerComponent al di fuori di {1, 2, 4, 8, 16} e uno stride di riga derivato superiore a 64,000,000 byte.
• inverse() rifiuta un predittore al di fuori di 10-15. Il predittore TIFF (2) non viene mai sottoposto a filtro inverso qui; effettuare prima la diramazione su isPngPredictor().
• inverse() rifiuta columns o colors inferiori a 1 e bitsPerComponent al di fuori dell’insieme consentito.
• inverse() rifiuta una geometria il cui prodotto dello stride causerebbe overflow dell’intero della piattaforma, prima di qualsiasi allocazione.
• inverse() rifiuta uno stride di riga superiore al limite massimo per riga di 64,000,000 byte, indipendentemente dalla lunghezza effettiva dell’input.
• inverse() restituisce una stringa vuota per un input vuoto; questo non è un errore.
• inverse() fa fallire uno stride di riga dichiarato più grande dell’intero input come riga troncata all’offset 0.
• inverse() fa fallire una riga parziale finale come riga troncata, indicando l’offset e i conteggi dei byte.
• inverse() fa fallire un tag di filtro per riga sconosciuto (diverso da 0-4) con il valore del tag e l’offset della riga.
• Una discrepanza tra la geometria dichiarata di /DecodeParms e il layout effettivo dello stream emerge come errore di parametro o di troncamento, mai come output silenziosamente corrotto.
• Il filtro Average utilizza la divisione intera, in linea con la semantica floor della specifica PNG.
• In questo modulo non avviene alcuna operazione crittografica. Il comportamento è identico nei deployment soggetti a vincoli FIPS.

Conformità

Dichiarazione	Standard	Clausola
Il parametro di filtro /Predictor seleziona l’algoritmo del predittore; i valori consentiti provengono dalla tabella dei valori del predittore.	ISO 32000-2:2020	§7.4.4.4
PDF definisce due gruppi di predittori: il gruppo TIFF è la singola funzione Predictor 2; il gruppo PNG è costituito dai tag 10-15.	ISO 32000-2:2020	§7.4.4.4
I valori validi di /BitsPerComponent sono 1, 2, 4, 8 e 16 con valore predefinito 8; /Colors è 1 o superiore con valore predefinito 1; /Columns ha valore predefinito 1.	ISO 32000-2:2020	§7.4.4.4
Le funzioni di ricostruzione per i tipi di filtro 0-4 operano byte per byte modulo 256; i byte di sinistra e della riga precedente assenti sono letti come zero.	W3C PNG (Third Edition)	§9.2
Il tipo di filtro Paeth calcola il PaethPredictor dei vicini di sinistra, superiore e superiore-sinistro e sceglie il più vicino.	W3C PNG (Third Edition)	§9.4

Tutte le clausole sono parafrasate; NextPDF non riproduce il testo normativo. Si tratta di dichiarazioni di funzionalità, non di certificazioni; NextPDF non detiene alcuna certificazione e non ne concede alcuna. La conformità della matematica di ricostruzione e dei valori predefiniti dei parametri è verificata dalla suite di unit test. Un framework completo per filtri di stream PDF, e l’inversione del predittore TIFF, sono fuori ambito per questo modulo.

Note di sviluppo

• Entrambe le classi sono distribuite fin da nextpdf/pro 3.0.0 e sono attuali nella 3.1.0.
• Il modulo è utilizzato dagli estrattori Diff e Classifier di Pro quando i loro input contengono un predittore.
• Effettuare la diramazione su isPngPredictor() prima di chiamare inverse(); il predittore 1 e il predittore TIFF non richiedono alcuna inversione PNG.
• Il modulo limita la propria allocazione per riga. I chiamanti che invertono i predittori su stream non attendibili dovrebbero comunque limitare a monte la dimensione dell’input decompresso, come fanno gli estrattori Pro.
• I predittori fissi (10-14) e Optimum (15) condividono un unico percorso di codice; il tag per riga guida la ricostruzione in entrambi i casi.
• I dettagli del meccanismo interno rimangono nella documentazione interna del repository sorgente e sono fuori ambito per questo manuale.

Confine di pubblicazione

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

Vedere anche

• Filter (funzionalità) — installazione, avvio rapido ed esempi d’uso in produzione.
• Diff — Riferimento approfondito — un consumatore del filtro inverso.
• Classifier — Riferimento approfondito — un consumatore del filtro inverso.