Pro редакция

Filter

Краткий обзор

NextPDF\Pro\Filter предоставляет два узких помощника: парсер словаря PDF /DecodeParms и обратный фильтр для предиктора PNG, применённого к потокам с FlateDecode. Это поддержка предикторов, используемая извлекателями Diff и Classifier из Pro; это не универсальный фреймворк фильтров.

Доступность и лицензирование

Эта возможность поставляется в составе NextPDF Pro (nextpdf/pro) и активируется лицензионным конвертом уровня Pro. Развёртывание без такого права доступа не загружает классы этой возможности. Сравните редакции и получите лицензию.

Классы Filter доступны всегда, когда установлен nextpdf/pro; никакой флаг возможности времени выполнения не ограничивает этот модуль.

Установка

composer require nextpdf/pro:^3

Концептуальный обзор

Потоки PDF могут быть сжаты FlateDecode и дополнительно предварительно обработаны предиктором для улучшения сжатия. ISO 32000-2:2020 §7.4.4.4 определяет параметры предиктора (/Predictor, /Columns, /Colors, /BitsPerComponent) и семейство предикторов PNG (теги 10–15).

DecodeParms разбирает фрагмент словаря /DecodeParms в неизменяемый объект-значение с разумными значениями по умолчанию (предиктор 1, столбцы 1, цвета 1, бит на компонент 8). isPngPredictor() истинно для тегов 10–15.
PngPredictor применяет обратное преобразование пяти типов фильтров PNG — None, Sub, Up, Average, Paeth — плюс Optimum (предиктор 15, тег на строку). Он проверяет параметры и вызывает InvalidArgumentException на значениях вне диапазона или на усечённой строке.

Этот модуль обращает существующий предиктор при чтении потока. Он не реализует полный набор фильтров потоков PDF и не предоставляет хуков для настройки фильтров.

Почему это работает именно так

Модуль обращает существующий предиктор, а не предлагает универсальный фреймворк фильтров. Извлекатели Diff и Classifier из Pro лишь читают то, что производитель уже записал, поэтому узкой области применения достаточно. Эта область позволяет ограничить каждый вход до обработки хоть одного байта. DecodeParms::fromDictionary() — это узкое место на этапе разбора: оно отклоняет отрицательную или чрезмерную геометрию и применяет значения по умолчанию DecodeParms::__construct(), где ключ отсутствует. PngPredictor перепроверяет эти границы на этапе применения, поэтому враждебный /DecodeParms вызывает типизированную ошибку, а не крупное выделение памяти. Вызывающий код ветвится по DecodeParms::isPngPredictor(), удерживая предиктор TIFF вне обратного фильтра, который обрабатывает только теги 10–15.

Проектная предыстория: Потоки и фильтры.

Контракт поведения

DecodeParms::fromDictionary(string $raw): self — сопоставление целых чисел, устойчивое к пробелам; отсутствующие ключи сохраняют свои значения по умолчанию.
PngPredictor::inverse(string $raw, int $columns, int $colors, int $bitsPerComponent, int $predictor): string — предиктор должен быть 10–15; столбцы и цвета должны быть ≥ 1; бит на компонент должен быть 1, 2, 4, 8 или 16; строка короче вычисленного шага вызывает InvalidArgumentException.
Детерминированность. Выход — чистая функция входных данных.

Поверхность публичного API

Тип	Вид	Ключевые члены
`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`

Пример кода — быстрый старт

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

Пример кода — продакшн

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

Граничные случаи и подводные камни

Предиктор TIFF (тег 2) распознаётся DecodeParms, но не обращается PngPredictor (который принимает только 10–15). Вызывающий код должен ветвиться по isPngPredictor().
Строка предиктора короче вычисленного шага отклоняется; она не усекается молча.
Шаг строки вычисляется из columns * colors * bitsPerComponent; несовпадение /DecodeParms с фактической раскладкой потока даёт ошибку параметра или усечения, а не повреждённый вывод.

Производительность

PngPredictor::inverse() линеен по длине потока с малой константой на байт. Разбор DecodeParms — это несколько ограниченных сопоставлений регулярных выражений. См. performance_budget.

Замечания по безопасности

Диапазоны параметров проверяются до любой обработки байтов, а усечённая строка вызывает исключение, а не чтение за границей. Вызывающий код, обращающий предикторы на недоверенных потоках, должен также ограничивать размер распаковки выше по конвейеру, как делают извлекатели Diff и Classifier из Pro.

Соответствие

Утверждение	Пункт стандарта	Статус
Параметры и значения по умолчанию `/DecodeParms`	ISO 32000-2:2020 §7.4.4.4	Проверено (набор модульных тестов)
Обратный фильтр предиктора PNG, теги 10–15	ISO 32000-2:2020 §7.4.4.4	Проверено (набор модульных тестов)
Полный фреймворк фильтров потоков PDF	—	Не поддерживается (вне области применения)

Резервный вариант Core / альтернатива

В Core не предоставлен аналог для обращения предиктора PNG. Собственная обработка потоков в Core внутренняя для движка и не входит в эту публичную поверхность.

Примечание о границе Enterprise

Это узкий помощник для предикторов. Это не криптографический фильтр, не санитайзер содержимого и не компонент реконструкции/обезвреживания данных; эти задачи вне области применения.

Граница публикации

Эта страница описывает только внешне наблюдаемое поведение и поддерживаемую публичную поверхность API. Внутренние пути пространств имён, вспомогательные классы, таблицы механизмов, имена файлов runbook и префиксы тикетов вне области применения.