Pro editie

Filter

In het kort

NextPDF\Pro\Filter biedt twee gerichte helpers: een parser voor de PDF- /DecodeParms-dictionary en een reverse-filter voor de PNG-predictor die wordt toegepast op FlateDecoded streams. Het is de predictorondersteuning die de Pro Diff- en Classifier-extractors gebruiken; het is geen algemeen filterframework.

Beschikbaarheid en licentie

Deze functionaliteit wordt geleverd in NextPDF Pro (nextpdf/pro) en wordt geactiveerd met een licentie-envelope op Pro-niveau. Een deployment zonder die rechten laadt de klassen van de functionaliteit niet. Vergelijk edities en vraag een licentie aan.

De Filter-klassen zijn beschikbaar zodra nextpdf/pro is geïnstalleerd; geen runtime-mogelijkheidsvlag bewaakt deze module.

Installatie

composer require nextpdf/pro:^3

Conceptueel overzicht

PDF-streams kunnen FlateDecode-gecomprimeerd zijn en daarnaast voorbewerkt worden met een predictor om de compressie te verbeteren. ISO 32000-2:2020 §7.4.4.4 definieert de predictorparameters (/Predictor, /Columns, /Colors, /BitsPerComponent) en de PNG-predictorfamilie (tags 10–15).

DecodeParms parseert een /DecodeParms-dictionaryfragment tot een immutable waarde-object met verstandige standaarden (predictor 1, columns 1, colors 1, bits-per-component 8). isPngPredictor() is waar voor tags 10–15.
PngPredictor past de inverse toe van de vijf PNG-filtertypen — None, Sub, Up, Average, Paeth — plus Optimum (predictor 15, tag per rij). Deze valideert parameters en werpt InvalidArgumentException bij waarden buiten bereik of een afgekapte rij.

Deze module keert een bestaande predictor om bij het lezen van een stream. Deze implementeert niet de volledige set PDF-streamfilters en biedt geen filter-afstemhooks.

Waarom het zo werkt

De module keert een bestaande predictor om in plaats van een algemeen filterframework te bieden. De Pro Diff- en Classifier-extractors lezen alleen wat een producer al heeft geschreven, dus een smalle scope is voldoende. Die scope laat elke invoer begrenzen voordat er ook maar één byte wordt verwerkt. DecodeParms::fromDictionary() is het parse-tijd-knelpunt: het wijst negatieve of te grote geometrie af en past de standaarden van DecodeParms::__construct() toe waar een sleutel ontbreekt. PngPredictor controleert die grenzen opnieuw bij het toepassen, zodat een vijandige /DecodeParms een getypeerde fout werpt in plaats van een grote allocatie. Callers vertakken op DecodeParms::isPngPredictor(), waardoor de TIFF-predictor buiten een reverse-filter blijft dat alleen tags 10–15 verwerkt.

Ontwerpachtergrond: Streams en filters.

Gedragscontract

DecodeParms::fromDictionary(string $raw): self — whitespace-tolerante integermatching; afwezige sleutels behouden hun standaarden.
PngPredictor::inverse(string $raw, int $columns, int $colors, int $bitsPerComponent, int $predictor): string — predictor moet 10–15 zijn; columns en colors moeten ≥ 1 zijn; bits-per-component moet 1, 2, 4, 8 of 16 zijn; een rij die korter is dan de berekende stride werpt InvalidArgumentException.
Determinisme. De uitvoer is een pure functie van de invoer.

Publiek API-oppervlak

Type	Soort	Belangrijkste leden
`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`

Codevoorbeeld — Snelstart

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

Codevoorbeeld — Productie

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

Randgevallen en valkuilen

De TIFF-predictor (tag 2) wordt door DecodeParms herkend, maar wordt niet reverse-filterd door PngPredictor (die alleen 10–15 accepteert). Callers moeten vertakken op isPngPredictor().
Een predictorrij die korter is dan de berekende stride wordt afgewezen; deze wordt niet stilzwijgend afgekapt.
De rij-stride wordt berekend uit columns * colors * bitsPerComponent; een /DecodeParms die niet overeenkomt met de werkelijke streamlay-out produceert een parameter- of afkappingsfout in plaats van corrupte uitvoer.

Prestaties

PngPredictor::inverse() is lineair in de streamlengte met een kleine per-byte- constante. DecodeParms-parsing is een paar begrensde reguliere-expressiematches. Zie performance_budget.

Beveiligingsnotities

Parameterbereiken worden gevalideerd vóór enige byteverwerking, en een afgekapte rij werpt in plaats van buiten de grenzen te lezen. Callers die predictoren omkeren op niet-vertrouwde streams moeten ook de gedecomprimeerde grootte stroomopwaarts begrenzen, zoals de Pro Diff- en Classifier-extractors doen.

Conformiteit

Claim	Spec-clausule	Status
`/DecodeParms`-parameters en standaarden	ISO 32000-2:2020 §7.4.4.4	Geverifieerd (unit suite)
PNG-predictor-reverse-filter, tags 10–15	ISO 32000-2:2020 §7.4.4.4	Geverifieerd (unit suite)
Volledig PDF-streamfilterframework	—	Niet ondersteund (buiten bereik)

Core-fallback / alternatief

Er is geen Core-equivalent blootgesteld voor PNG-predictoromkering. De eigen streamverwerking van Core is intern in de engine en geen onderdeel van dit publieke oppervlak.

Enterprise-grensnotitie

Dit is een smalle predictorhelper. Het is geen cryptografische filter, een content-sanitizer of een data-reconstructie-/disarm-component; die aangelegenheden vallen buiten het bereik.

Publicatiegrens

Deze pagina documenteert alleen extern waarneembaar gedrag en het ondersteunde publieke API-oppervlak. Interne namespace-paden, helperklassen, mechanismetabellen, runbook-bestandsnamen en ticketprefixen vallen buiten het bereik.