Pro edycja

Filter

W skrócie

NextPDF\Pro\Filter dostarcza dwóch skupionych pomocników: parser słownika PDF /DecodeParms oraz filtr odwrotny dla predyktora PNG zastosowanego do strumieni zakodowanych FlateDecode. To wsparcie predyktorów używane przez ekstraktory Pro Diff i Classifier; nie jest ogólnym frameworkiem filtrów.

Dostępność i licencjonowanie

Ta funkcja jest dostarczana w NextPDF Pro (nextpdf/pro) i aktywuje się z kopertą licencyjną poziomu Pro. Wdrożenie bez tego uprawnienia nie ładuje klas tej funkcji. Porównaj edycje i uzyskaj licencję.

Klasy Filter są dostępne zawsze, gdy zainstalowano nextpdf/pro; żadna flaga możliwości w czasie wykonywania nie bramkuje tego modułu.

Instalacja

composer require nextpdf/pro:^3

Przegląd koncepcyjny

Strumienie PDF mogą być skompresowane FlateDecode i dodatkowo wstępnie przetworzone predyktorem dla poprawy kompresji. ISO 32000-2:2020 §7.4.4.4 definiuje parametry predyktora (/Predictor, /Columns, /Colors, /BitsPerComponent) oraz rodzinę predyktorów PNG (tagi 10–15).

DecodeParms parsuje fragment słownika /DecodeParms na niezmienialny obiekt wartości z rozsądnymi wartościami domyślnymi (predyktor 1, kolumny 1, kolory 1, bity-na-komponent 8). isPngPredictor() jest prawdziwe dla tagów 10–15.
PngPredictor stosuje odwrotność pięciu typów filtrów PNG — None, Sub, Up, Average, Paeth — oraz Optimum (predyktor 15, tag na wiersz). Waliduje parametry i zgłasza InvalidArgumentException dla wartości poza zakresem lub obciętego wiersza.

Ten moduł odwraca istniejący predyktor podczas odczytu strumienia. Nie implementuje pełnego zestawu filtrów strumieni PDF i nie udostępnia haków do strojenia filtrów.

Dlaczego działa w ten sposób

Moduł odwraca istniejący predyktor, zamiast oferować ogólny framework filtrów. Ekstraktory Pro Diff i Classifier odczytują tylko to, co producent już zapisał, więc wąski zakres wystarcza. Ten zakres pozwala ograniczyć każde wejście, zanim przetworzony zostanie choćby jeden bajt. DecodeParms::fromDictionary() to punkt kontrolny na etapie parsowania: odrzuca ujemną lub nadmiarową geometrię i stosuje wartości domyślne z DecodeParms::__construct() tam, gdzie brakuje klucza. PngPredictor ponownie sprawdza te granice na etapie zastosowania, więc wrogie /DecodeParms zgłasza typowany błąd zamiast dużej alokacji. Wywołujący rozgałęziają się na DecodeParms::isPngPredictor(), utrzymując predyktor TIFF poza filtrem odwrotnym, który obsługuje wyłącznie tagi 10–15.

Tło projektowe: Strumienie i filtry.

Kontrakt zachowania

DecodeParms::fromDictionary(string $raw): self — dopasowanie liczb całkowitych tolerancyjne wobec białych znaków; nieobecne klucze zachowują swoje wartości domyślne.
PngPredictor::inverse(string $raw, int $columns, int $colors, int $bitsPerComponent, int $predictor): string — predyktor musi być 10–15; kolumny i kolory muszą być ≥ 1; bity-na-komponent muszą wynosić 1, 2, 4, 8 lub 16; wiersz krótszy niż obliczony krok (stride) zgłasza InvalidArgumentException.
Determinizm. Wyjście jest czystą funkcją wejść.

Publiczna powierzchnia API

Typ	Rodzaj	Kluczowe składowe
`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`

Przykład kodu — Szybki start

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

Przykład kodu — Produkcja

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

Przypadki brzegowe i pułapki

Predyktor TIFF (tag 2) jest rozpoznawany przez DecodeParms, lecz nie jest filtrowany odwrotnie przez PngPredictor (który przyjmuje tylko 10–15). Wywołujący powinni rozgałęziać się na isPngPredictor().
Wiersz predyktora krótszy niż obliczony krok (stride) jest odrzucany; nie jest po cichu obcinany.
Krok wiersza jest obliczany z columns * colors * bitsPerComponent; niezgodność /DecodeParms względem rzeczywistego układu strumienia daje błąd parametru lub obcięcia, zamiast uszkodzonego wyjścia.

Wydajność

PngPredictor::inverse() jest liniowe względem długości strumienia z małą stałą na bajt. Parsowanie DecodeParms to kilka ograniczonych dopasowań wyrażeń regularnych. Zobacz performance_budget.

Uwagi dotyczące bezpieczeństwa

Zakresy parametrów są walidowane przed jakimkolwiek przetwarzaniem bajtów, a obcięty wiersz zgłasza wyjątek, zamiast czytać poza granicami. Wywołujący odwracający predyktory na niezaufanych strumieniach powinni również ograniczyć zdekompresowany rozmiar wcześniej, tak jak robią to ekstraktory Pro Diff i Classifier.

Konformancja

Twierdzenie	Klauzula specyfikacji	Status
Parametry i wartości domyślne `/DecodeParms`	ISO 32000-2:2020 §7.4.4.4	Verified (unit suite)
Filtr odwrotny predyktora PNG, tagi 10–15	ISO 32000-2:2020 §7.4.4.4	Verified (unit suite)
Pełny framework filtrów strumieni PDF	—	Not supported (out of scope)

Rozwiązanie awaryjne / alternatywa w Core

Nie jest udostępniony odpowiednik w Core dla odwracania predyktora PNG. Własna obsługa strumieni w Core jest wewnętrzna dla silnika i nie jest częścią tej publicznej powierzchni.

Nota o granicy Enterprise

To wąski pomocnik predyktorów. Nie jest filtrem kryptograficznym, sanityzatorem zawartości ani komponentem rekonstrukcji/rozbrojenia danych; te kwestie są poza zakresem.

Granica publikacji

Ta strona dokumentuje wyłącznie zachowanie obserwowalne zewnętrznie oraz wspieraną publiczną powierzchnię API. Wewnętrzne ścieżki przestrzeni nazw, klasy pomocnicze, tabele mechanizmów, nazwy plików runbooków i prefiksy zgłoszeń są poza zakresem.