Filter — Diepe referentie

In één oogopslag

Deze pagina is de referentie op contractniveau voor de NextPDF Pro Filter-module, namespace NextPDF\Pro\Filter. Het oppervlak bestaat uit twee klassen. DecodeParms parseert een fragment van een PDF /DecodeParms-dictionary tot een onveranderlijk, op grenzen gecontroleerd value object. PngPredictor keert de PNG-predictorfamilie (tags 10-15) om op FlateDecoded stream-bytes. De module bedient de Pro Diff- en Classifier-extractors. Het is geen algemeen stream-filter-framework. Deze pagina beschrijft de publieke API, het contract voor het waarneembare gedrag en de getypeerde faalmodi. Gebruiksadvies en codevoorbeelden staan op de Filter-capaciteitspagina.

Beschikbaarheid en licenties

Deze capaciteit wordt geleverd in NextPDF Pro (nextpdf/pro) en wordt geactiveerd met een licentie-envelop van het Pro-niveau. Een deployment zonder die entitlement laadt de klassen van de capaciteit niet. Vergelijk edities en verkrijg een licentie.

Geen runtime-capaciteitsflag gate’t deze module. De Filter-klassen zijn beschikbaar wanneer nextpdf/pro is geïnstalleerd.

Publiek API-oppervlak

Symbool	Parameters	Standaardgedrag	Retourneert	Werpt of faalt met	Opmerkingen
DecodeParms	constructor: int $predictor = 1, int $columns = 1, int $colors = 1, int $bitsPerComponent = 8	Standaardwaarden coderen “geen predictor”	—	—	final readonly; alle vier de eigenschappen zijn public en onveranderlijk
DecodeParms::fromDictionary()	string $raw — ruwe dictionary-tekst, omringende object-body wordt getolereerd	Afwezige sleutels behouden hun standaardwaarden; matching is tolerant voor witruimte	self	InvalidArgumentException	Knelpunt tijdens parsen; grenzen staan in het gedragscontract
DecodeParms::isPngPredictor()	geen	Zuivere predicaat; geen I/O	bool — true voor predictor 10-15	—	Vertak hierop voordat je de reverse-filter aanroept
PngPredictor	—	Stateless	—	—	final; het enige entry point is de statische inverse()
PngPredictor::inverse()	string $raw, int $columns, int $colors, int $bitsPerComponent, int $predictor	Filtert rij voor rij terug op de tag per rij; lege invoer retourneert een lege string	string — gereconstrueerde payload met filtertags verwijderd	InvalidArgumentException	Accepteert uitsluitend predictor 10-15; de TIFF-predictor valt buiten het bereik

Signatures van de entry points

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

Gedragscontract

Parsen van /DecodeParms

DecodeParms::fromDictionary() matcht vier herkende sleutels als integers in ruwe dictionary-tekst: /Predictor, /Columns, /Colors en /BitsPerComponent. Dit zijn de predictorparameters die ISO 32000-2:2020 §7.4.4.4 definieert voor de filters LZWDecode en FlateDecode. Matching is tolerant voor witruimte en overleeft omringende PDF-tokens. Afwezige sleutels behouden hun standaardwaarden: predictor 1, columns 1, colors 1, bits-per-component 8. Aanwezige waarden worden fail-closed gevalideerd tijdens het parsen, voordat enige geometrie de rijallocatie van de reverse-filter kan bereiken:

• Een aanwezige negatieve waarde voor een herkende sleutel wordt geweigerd.
• /Columns boven 1.000.000 wordt geweigerd.
• /Colors boven 32 wordt geweigerd.
• /BitsPerComponent buiten {1, 2, 4, 8, 16} wordt geweigerd.
• Een afgeleide rijstride boven 64.000.000 bytes wordt geweigerd.

isPngPredictor() retourneert true wanneer de geparseerde predictor 10 tot en met 15 is. Predictor 1 (geen predictie) en predictor 2 (de TIFF-groep) retourneren false.

Rijgeometrie

PngPredictor::inverse() verbruikt een FlateDecoded byte-stream waarin elke rij wordt voorafgegaan door een filtertag van één byte. Het geeft de gereconstrueerde payload uit met de tags verwijderd. De breedte van de rij-payload is ceil(columns * colors * bitsPerComponent / 8) bytes; de rijstride voegt één tagbyte toe. De offset van de linkerbuur (bytes per pixel) is max(1, floor(colors * bitsPerComponent / 8)), dus sub-byte-packings worden naar één byte afgerond. Het filteren werkt op hele bytes, ongeacht de bitdiepte, conform de PNG-filtersemantiek.

Reconstructie per rij

Tag	Filter	Reconstructie
0	None	doorgeven
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)

Alle sommen worden modulo 256 genomen. Voor de eerste rij, en voor bytes links van de eerste pixel, wordt de ontbrekende buur als nul gelezen, conform W3C PNG §9.2. De omgekeerde bewerking wordt volledig aangestuurd door de tag per rij. Dat is het conforme gedrag voor zowel de vaste predictors (10-14) als Optimum (15) volgens ISO 32000-2:2020 §7.4.4.4, waardoor variantie in de tag van de writer wordt getolereerd.

Validatielagen

Parametervalidatie draait bij ontwerp in twee lagen. DecodeParms is het knelpunt tijdens het parsen en weigert vijandige magnitudes als eerste. PngPredictor::inverse() behoudt zijn eigen controles als tweede laag: bereikcontroles op alle vier de parameters, overflow-guards die afzonderlijke factoren vergelijken met PHP_INT_MAX voordat het strideproduct wordt gevormd, hetzelfde plafond van 64.000.000 bytes per rij, en een aan de invoer evenredige grens die een gedeclareerde stride die groter is dan de volledige invoer weigert voordat er enige rijbuffer wordt gealloceerd.

Determinisme

Beide entry points zijn zuivere statische functies van hun invoer. Er is geen I/O, geen logging en geen globale state. De runtime is lineair in de invoerlengte met een kleine constante per byte. Het parsen van /DecodeParms betreft enkele begrensde matches met reguliere expressies. Budgetten staan in de frontmatter performance_budget.

Randgevallen en faalmodi

Elke fout in deze module werpt InvalidArgumentException met de overtredende waarde benoemd in het bericht.

• fromDictionary() weigert een aanwezige negatieve waarde voor een herkende sleutel.
• fromDictionary() weigert /Columns boven 1.000.000 en /Colors boven 32.
• fromDictionary() weigert /BitsPerComponent buiten {1, 2, 4, 8, 16} en een afgeleide rijstride boven 64.000.000 bytes.
• inverse() weigert een predictor buiten 10-15. De TIFF-predictor (2) wordt hier nooit teruggefilterd; vertak eerst op isPngPredictor().
• inverse() weigert columns of colors onder 1 en bitsPerComponent buiten de legale set.
• inverse() weigert geometrie waarvan het strideproduct het platform-integer zou overflowen, voordat er enige allocatie plaatsvindt.
• inverse() weigert een rijstride boven het plafond van 64.000.000 bytes per rij, onafhankelijk van de werkelijke invoerlengte.
• inverse() retourneert een lege string voor lege invoer; dat is geen fout.
• inverse() laat een gedeclareerde rijstride die groter is dan de volledige invoer falen als een afgekapte rij op offset 0.
• inverse() laat een afsluitende gedeeltelijke rij falen als een afgekapte rij, met vermelding van de offset en de byte-tellingen.
• inverse() laat een onbekende filtertag per rij (niet 0-4) falen met de tagwaarde en de rij-offset.
• Een mismatch tussen de gedeclareerde /DecodeParms-geometrie en de werkelijke stream-layout komt naar boven als een parameter- of afkappingsfout, nooit als stil corrupte uitvoer.
• Het Average-filter gebruikt integer-deling, conform de floor-semantiek van de PNG-specificatie.
• In deze module vindt geen cryptografische bewerking plaats. Het gedrag is identiek in FIPS-beperkte deployments.

Conformiteit

Bewering	Standaard	Clausule
De filterparameter /Predictor selecteert het predictor-algoritme; toegestane waarden komen uit de predictor-waardetabel.	ISO 32000-2:2020	§7.4.4.4
PDF definieert twee predictorgroepen: de TIFF-groep is de enkele Predictor 2-functie; de PNG-groep is tags 10-15.	ISO 32000-2:2020	§7.4.4.4
Geldige waarden voor /BitsPerComponent zijn 1, 2, 4, 8 en 16 met standaard 8; /Colors is 1 of hoger met standaard 1; /Columns heeft standaard 1.	ISO 32000-2:2020	§7.4.4.4
Reconstructiefuncties voor filtertypen 0-4 werken byte-gewijs modulo 256; afwezige linker- en vorige-rij-bytes worden als nul gelezen.	W3C PNG (Third Edition)	§9.2
Het Paeth-filtertype berekent de PaethPredictor van de linker-, boven- en linksboven-buur en kiest de dichtstbijzijnde.	W3C PNG (Third Edition)	§9.4

Alle clausules zijn geparafraseerd; NextPDF reproduceert geen normatieve tekst. Dit zijn capaciteitsbeweringen, geen certificeringen; NextPDF bezit geen certificering en verleent er geen. De conformiteit van de reconstructiewiskunde en de standaard parameterwaarden wordt beproefd door de unit-suite. Een volledig PDF-stream-filter-framework, en het omkeren van de TIFF-predictor, vallen buiten het bereik van deze module.

Ontwikkelnotities

• Beide klassen worden geleverd sinds nextpdf/pro 3.0.0 en zijn actueel in 3.1.0.
• De module wordt gebruikt door de Pro Diff- en Classifier-extractors wanneer hun invoer een predictor bevat.
• Vertak op isPngPredictor() voordat je inverse() aanroept; predictor 1 en de TIFF-predictor hebben geen PNG-omkering nodig.
• De module begrenst zijn eigen allocatie per rij. Aanroepers die predictors op onvertrouwde streams omkeren, moeten de grootte van de gedecomprimeerde invoer nog steeds stroomopwaarts begrenzen, zoals de Pro-extractors doen.
• Vaste predictors (10-14) en Optimum (15) delen één codepad; de tag per rij stuurt de reconstructie in beide gevallen aan.
• Interne mechanismedetails blijven in de interne documentatie van de source-repository en vallen buiten het bereik van deze handleiding.

Publicatiegrens

Deze pagina documenteert uitsluitend extern waarneembaar gedrag en het ondersteunde publieke API-oppervlak. Interne namespace-paden, hulpklassen, mechanismetabellen, runbook-bestandsnamen en ticket-prefixen vallen buiten het bereik.

Zie ook

• Filter (capaciteit) — installatie, snelstart en productiegebruiksvoorbeelden.
• Diff — Diepe referentie — een consument van de reverse-filter.
• Classifier — Diepe referentie — een consument van de reverse-filter.