Filter

概要

NextPDF\Pro\Filter は、的を絞った 2 つのヘルパーを提供します。PDF の /DecodeParms 辞書のパーサーと、FlateDecode されたストリームに適用された PNG 予測子の逆フィルターです。これは Pro の Diff および Classifier の抽出器が用いる予測子サポートであり、汎用のフィルターフレームワークではありません。

提供状況とライセンス

この機能は 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 辞書フラグメントを、妥当なデフォルト （predictor 1、columns 1、colors 1、bits-per-component 8）を持つ不変の値オブジェクトに解析します。isPngPredictor() はタグ 10〜15 に対して true になります。
• PngPredictor は、5 つの PNG フィルタータイプ（None、Sub、Up、 Average、Paeth）の逆変換に加えて、Optimum（predictor 15、行ごとのタグ）を適用します。パラメーターを検証し、範囲外の値や切り詰められた行に対して InvalidArgumentException を発生させます。

このモジュールは、ストリームを読み取る際に 既存の 予測子を逆適用します。 PDF ストリームフィルターの完全なセットを実装するものではなく、フィルター調整のフックも提供しません。

この設計である理由

このモジュールは、汎用のフィルターフレームワークを提供するのではなく、 既存の 予測子を逆適用します。Pro の Diff および Classifier の抽出器はプロデューサーがすでに書き込んだものを読むだけなので、狭い範囲で十分です。 その範囲により、あらゆる入力を、いずれかのバイトが処理される前に上限で制限できます。DecodeParms::fromDictionary() は解析時のチョークポイントで、 負値や過大なジオメトリを拒否し、キーが欠落している箇所には DecodeParms::__construct() のデフォルトを適用します。PngPredictor は適用時にそれらの上限を再チェックするため、敵対的な /DecodeParms は大きな割り当てではなく型付きのエラーを発生させます。呼び出し側は DecodeParms::isPngPredictor() で分岐し、タグ 10〜15 のみを扱う逆フィルターから TIFF 予測子を締め出します。

設計の背景: Streams and filters。

振る舞いの契約

• DecodeParms::fromDictionary(string $raw): self — 空白に寛容な整数マッチング。欠落しているキーはデフォルトを維持します。
• PngPredictor::inverse(string $raw, int $columns, int $colors, int $bitsPerComponent, int $predictor): string — predictor は 10〜15 でなければなりません。columns と colors は 1 以上でなければなりません。bits-per-component は 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 を参照してください。

セキュリティに関する注意

パラメーターの範囲は、いかなるバイト処理よりも前に検証され、切り詰められた行は境界外を読み取るのではなく例外を発生させます。信頼できないストリームに対して予測子を逆適用する呼び出し側は、Pro の Diff および Classifier の抽出器と同様に、上流で解凍後サイズも上限で制限すべきです。

適合性

主張	仕様の条項	ステータス
/DecodeParms のパラメーターとデフォルト	ISO 32000-2:2020 §7.4.4.4	検証済み（ユニットスイート）
PNG 予測子の逆フィルター、タグ 10〜15	ISO 32000-2:2020 §7.4.4.4	検証済み（ユニットスイート）
完全な PDF ストリームフィルターフレームワーク	—	非対応（範囲外）

Core のフォールバック/代替手段

PNG 予測子の逆適用に相当する Core の機能は公開されていません。Core 自身のストリーム処理はエンジン内部にあり、この公開サーフェスの一部ではありません。

Enterprise の境界に関する注意

これは範囲の狭い予測子ヘルパーです。暗号フィルター、コンテンツサニタイザー、データ再構築/武装解除コンポーネントのいずれでもありません。 それらの関心事は範囲外です。

公開の境界

このページは、外部から観測可能な振る舞いと、サポートされる公開 API サーフェスのみを記述します。内部の名前空間パス、ヘルパークラス、メカニズムの表、 Runbook のファイル名、チケットのプレフィックスは範囲外です。

関連項目

• Filter リファレンス
• Diff
• Classifier
• PDF 2.0 仕様