Filter

Auf einen Blick

NextPDF\Pro\Filter stellt zwei fokussierte Helfer bereit: einen Parser für das PDF-Dictionary /DecodeParms und einen Umkehrfilter für den PNG-Prädiktor, der auf FlateDecode-Streams angewendet wird. Es ist die Prädiktor-Unterstützung, die die Pro-Diff- und Classifier-Extraktoren nutzen; es ist kein allgemeines Filter-Framework.

Verfügbarkeit & Lizenzierung

Diese Funktion wird in NextPDF Pro (nextpdf/pro) ausgeliefert und aktiviert sich mit einem Lizenz-Envelope der Pro-Stufe. Eine Bereitstellung ohne diese Berechtigung lädt die Klassen der Funktion nicht. Editionen vergleichen und eine Lizenz erwerben.

Die Filter-Klassen sind verfügbar, sobald nextpdf/pro installiert ist; kein Laufzeit-Fähigkeits-Flag schaltet dieses Modul frei.

Installation

composer require nextpdf/pro:^3

Konzeptioneller Überblick

PDF-Streams können FlateDecode-komprimiert und zusätzlich mit einem Prädiktor vorverarbeitet sein, um die Kompression zu verbessern. ISO 32000-2:2020 §7.4.4.4 definiert die Prädiktor-Parameter (/Predictor, /Columns, /Colors, /BitsPerComponent) und die PNG-Prädiktor-Familie (Tags 10–15).

• DecodeParms parst ein /DecodeParms-Dictionary-Fragment in ein unveränderliches Wertobjekt mit sinnvollen Standardwerten (Prädiktor 1, Spalten 1, Farben 1, Bits-pro-Komponente 8). isPngPredictor() ist für die Tags 10–15 wahr.
• PngPredictor wendet die Inverse der fünf PNG-Filtertypen — None, Sub, Up, Average, Paeth — plus Optimum (Prädiktor 15, Tag je Zeile) an. Es validiert Parameter und löst InvalidArgumentException bei Werten außerhalb des Bereichs oder einer abgeschnittenen Zeile aus.

Dieses Modul kehrt beim Lesen eines Streams einen vorhandenen Prädiktor um. Es implementiert nicht den vollständigen Satz an PDF-Stream-Filtern und es bietet keine Filter-Tuning-Hooks.

Warum es so funktioniert

Das Modul kehrt einen vorhandenen Prädiktor um, statt ein allgemeines Filter-Framework anzubieten. Die Pro-Diff- und Classifier-Extraktoren lesen nur, was ein Producer bereits geschrieben hat, daher genügt ein enger Geltungsbereich. Dieser Geltungsbereich erlaubt es, jede Eingabe zu begrenzen, bevor ein einziges Byte verarbeitet wird. DecodeParms::fromDictionary() ist der Engpass zur Parse-Zeit: Es weist negative oder überdimensionierte Geometrie ab und wendet die Standardwerte von DecodeParms::__construct() an, wo ein Schlüssel fehlt. PngPredictor prüft diese Grenzen zur Anwendungszeit erneut, sodass ein bösartiges /DecodeParms einen typisierten Fehler auslöst statt einer großen Speicherallokation. Aufrufer verzweigen anhand von DecodeParms::isPngPredictor() und halten so den TIFF-Prädiktor aus einem Umkehrfilter heraus, der nur die Tags 10–15 behandelt.

Entwurfshintergrund: Streams und Filter.

Verhaltensvertrag

• DecodeParms::fromDictionary(string $raw): self — whitespace-tolerantes Ganzzahl-Matching; fehlende Schlüssel behalten ihre Standardwerte.
• PngPredictor::inverse(string $raw, int $columns, int $colors, int $bitsPerComponent, int $predictor): string — der Prädiktor muss 10–15 sein; Spalten und Farben müssen ≥ 1 sein; Bits-pro-Komponente muss 1, 2, 4, 8 oder 16 sein; eine Zeile, die kürzer als der berechnete Schritt (Stride) ist, löst InvalidArgumentException aus.
• Determinismus. Die Ausgabe ist eine reine Funktion der Eingaben.

Öffentliche API-Oberfläche

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

Codebeispiel — Schnellstart

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

Codebeispiel — Produktion

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

Randfälle & Fallstricke

• Der TIFF-Prädiktor (Tag 2) wird von DecodeParms erkannt, aber nicht von PngPredictor umgekehrt (das nur 10–15 akzeptiert). Aufrufer sollten anhand von isPngPredictor() verzweigen.
• Eine Prädiktor-Zeile, die kürzer als der berechnete Schritt ist, wird abgewiesen; sie wird nicht stillschweigend abgeschnitten.
• Der Zeilenschritt wird aus columns * colors * bitsPerComponent berechnet; nicht übereinstimmende /DecodeParms gegenüber dem tatsächlichen Stream-Layout erzeugen einen Parameter- oder Abschneidefehler statt beschädigter Ausgabe.

Performance

PngPredictor::inverse() ist linear in der Stream-Länge mit einer kleinen Konstante je Byte. Das Parsen von DecodeParms sind einige begrenzte Treffer regulärer Ausdrücke. Siehe performance_budget.

Sicherheitshinweise

Die Parameterbereiche werden vor jeglicher Byteverarbeitung validiert, und eine abgeschnittene Zeile löst aus, statt außerhalb der Grenzen zu lesen. Aufrufer, die Prädiktoren auf nicht vertrauenswürdigen Streams umkehren, sollten auch die dekomprimierte Größe vorgelagert begrenzen, wie es die Pro-Diff- und Classifier-Extraktoren tun.

Konformität

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)

Core-Rückfalloption / Alternative

Für die PNG-Prädiktor-Umkehrung wird kein Core-Äquivalent freigelegt. Die eigene Stream-Behandlung von Core ist intern in der Engine und nicht Teil dieser öffentlichen Oberfläche.

Hinweis zur Enterprise-Abgrenzung

Dies ist ein enger Prädiktor-Helfer. Er ist kein kryptografischer Filter, kein Inhalts-Bereiniger und keine Datenrekonstruktions-/Disarm-Komponente; diese Anliegen liegen außerhalb des Geltungsbereichs.

Veröffentlichungsgrenze

Diese Seite dokumentiert ausschließlich extern beobachtbares Verhalten und die unterstützte öffentliche API-Oberfläche. Interne Namespace-Pfade, Helferklassen, Mechanismus-Tabellen, Runbook-Dateinamen und Ticket-Präfixe liegen außerhalb des Geltungsbereichs.

Siehe auch

• Filter-Referenz
• Diff
• Classifier
• PDF-2.0-Spezifikationen