Pro 에디션

필터

한눈에 보기

NextPDF\Pro\Filter는 두 가지 집중된 헬퍼를 제공합니다. 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 딕셔너리 조각을 합리적인 기본값(예측기 1, 열 1, 색상 1, 컴포넌트당 비트 8)을 갖춘 불변 값 객체로 파싱합니다. isPngPredictor()는 태그 10–15에 대해 true입니다.
**PngPredictor**는 다섯 가지 PNG 필터 유형 — None, Sub, Up, Average, Paeth —의 역과 더불어 Optimum(예측기 15, 행별 태그)을 적용합니다. 매개변수를 검증하며 범위를 벗어난 값이나 잘린 행에 대해 InvalidArgumentException을 발생시킵니다.

이 모듈은 스트림을 읽을 때 기존 예측기를 역적용합니다. PDF 스트림 필터의 전체 집합을 구현하지 않으며 필터 튜닝 훅을 제공하지 않습니다.

이렇게 동작하는 이유

이 모듈은 범용 필터 프레임워크를 제공하기보다 기존 예측기를 역적용합니다. Pro Diff 및 Classifier 추출기는 생산자가 이미 작성한 것만 읽으므로 좁은 범위로 충분합니다. 그 범위 덕분에 어떤 바이트도 처리되기 전에 모든 입력을 경계 지을 수 있습니다. DecodeParms::fromDictionary()는 파싱 시점의 병목 지점입니다. 음수이거나 지나치게 큰 기하 형태를 거부하고, 키가 없는 경우 DecodeParms::__construct() 기본값을 적용합니다. PngPredictor는 적용 시점에 이러한 경계를 다시 검사하므로 악의적인 /DecodeParms는 대규모 할당 대신 타입이 지정된 오류를 발생시킵니다. 호출자는 DecodeParms::isPngPredictor()에서 분기하여, 태그 10–15만 처리하는 역필터로부터 TIFF 예측기를 배제합니다.

설계 배경: 스트림과 필터.

동작 계약

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를 참조하십시오.

보안 참고

매개변수 범위는 어떤 바이트 처리보다 먼저 검증되며, 잘린 행은 범위를 벗어나 읽는 대신 예외를 발생시킵니다. 신뢰할 수 없는 스트림에서 예측기를 역적용하는 호출자는 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 표면만 설명합니다. 내부 네임스페이스 경로, 헬퍼 클래스, 메커니즘 표, 런북 파일명, 티켓 접두사는 범위 밖입니다.