Filter — 심층 참조

한눈에 보기

이 페이지는 NextPDF Pro Filter 모듈(네임스페이스 NextPDF\Pro\Filter)에 대한 계약 수준의 참조입니다. 표면은 두 클래스로 구성됩니다. DecodeParms는 PDF /DecodeParms 딕셔너리 조각을 불변이며 경계 검사된 값 객체로 파싱합니다. PngPredictor는 FlateDecode된 스트림 바이트에서 PNG 예측기 계열(태그 10-15)을 역방향으로 처리합니다. 이 모듈은 Pro Diff 및 Classifier 추출기를 지원합니다. 범용 스트림 필터 프레임워크가 아닙니다. 이 페이지는 공개 API, 관찰 가능한 동작 계약, 그리고 유형화된 실패 모드를 명시합니다. 사용 지침과 코드 샘플은 Filter 기능 페이지에 있습니다.

가용성 및 라이선싱

이 기능은 NextPDF Pro(nextpdf/pro)에 포함되어 출시되며 Pro 등급 라이선스 엔벨로프로 활성화됩니다. 해당 권한이 없는 배포 환경에서는 이 기능의 클래스가 로드되지 않습니다. 에디션 비교 및 라이선스 받기.

이 모듈을 게이트하는 런타임 기능 플래그는 없습니다. Filter 클래스는 nextpdf/pro가 설치되어 있으면 언제나 사용할 수 있습니다.

공개 API 표면

Symbol	Parameters	Default behavior	Returns	Throws or fails with	Notes
DecodeParms	constructor: int $predictor = 1, int $columns = 1, int $colors = 1, int $bitsPerComponent = 8	기본값은 “예측기 없음”을 인코딩합니다	—	—	final readonly; 네 속성 모두 public이며 불변입니다
DecodeParms::fromDictionary()	string $raw — 원시 딕셔너리 텍스트, 주변 객체 본문 허용	없는 키는 기본값을 유지하며, 매칭은 공백에 관대합니다	self	InvalidArgumentException	파싱 시점의 병목 지점; 경계는 동작 계약에 나열됩니다
DecodeParms::isPngPredictor()	none	순수 술어; I/O 없음	bool — 예측기 10-15에 대해 true	—	역필터를 호출하기 전에 이 값으로 분기하십시오
PngPredictor	—	Stateless	—	—	final; 유일한 진입점은 정적 inverse()입니다
PngPredictor::inverse()	string $raw, int $columns, int $colors, int $bitsPerComponent, int $predictor	행별 태그에 따라 한 행씩 역필터링하며, 빈 입력은 빈 문자열을 반환합니다	string — 필터 태그가 제거된 재구성 페이로드	InvalidArgumentException	예측기 10-15만 허용; TIFF 예측기는 범위 밖입니다

진입점 시그니처

public function __construct(
    public int $predictor = 1,
    public int $columns = 1,
    public int $colors = 1,
    public int $bitsPerComponent = 8,
) {}

public static function fromDictionary(string $raw): self

public function isPngPredictor(): bool

public static function inverse(
    string $raw,
    int $columns,
    int $colors,
    int $bitsPerComponent,
    int $predictor,
): string

동작 계약

/DecodeParms 파싱

DecodeParms::fromDictionary()는 원시 딕셔너리 텍스트에서 인식된 네 개의 키를 정수로 매칭합니다: /Predictor, /Columns, /Colors, /BitsPerComponent. 이들은 ISO 32000-2:2020 §7.4.4.4이 LZWDecode 및 FlateDecode 필터에 대해 정의하는 예측기 매개변수입니다. 매칭은 공백에 관대하며 주변 PDF 토큰이 있어도 견딥니다. 없는 키는 기본값을 유지합니다: 예측기 1, 열 1, 색 1, 컴포넌트당 비트 8. 존재하는 값은 파싱 시점에, 어떤 기하값이라도 역필터의 행 할당에 도달하기 전에 fail-closed 방식으로 검증됩니다:

• 인식된 키에 대한 음수 값이 존재하면 거부됩니다.
• /Columns가 1,000,000을 초과하면 거부됩니다.
• /Colors가 32를 초과하면 거부됩니다.
• /BitsPerComponent가 {1, 2, 4, 8, 16} 밖이면 거부됩니다.
• 도출된 행 스트라이드가 64,000,000바이트를 초과하면 거부됩니다.

isPngPredictor()는 파싱된 예측기가 10에서 15까지일 때 true를 반환합니다. 예측기 1(예측 없음)과 예측기 2(TIFF 그룹)는 false를 반환합니다.

행 기하 구조

PngPredictor::inverse()는 각 행 앞에 1바이트 필터 태그가 붙은 FlateDecode된 바이트 스트림을 소비합니다. 태그가 제거된 재구성 페이로드를 방출합니다. 행 페이로드 폭은 ceil(columns * colors * bitsPerComponent / 8) 바이트이며, 행 스트라이드는 태그 1바이트를 더합니다. 왼쪽 이웃 오프셋(픽셀당 바이트)은 max(1, floor(colors * bitsPerComponent / 8))이므로, 하위 바이트 패킹은 1바이트로 내림됩니다. 필터링은 비트 깊이와 무관하게 온전한 바이트 단위로 작동하며, 이는 PNG 필터 의미론과 일치합니다.

행별 재구성

Tag	Filter	Reconstruction
0	None	passthrough
1	Sub	recon[x] = filt[x] + recon[x-bpp]
2	Up	recon[x] = filt[x] + prior[x]
3	Average	recon[x] = filt[x] + floor((recon[x-bpp] + prior[x]) / 2)
4	Paeth	recon[x] = filt[x] + Paeth(left, up, up-left)

모든 합은 256으로 나눈 나머지로 계산됩니다. 첫 번째 행과 첫 픽셀 왼쪽의 바이트에 대해서는, 없는 이웃이 W3C PNG §9.2에 따라 0으로 읽힙니다. 역연산은 전적으로 행별 태그에 의해 구동됩니다. 이는 ISO 32000-2:2020 §7.4.4.4에 따라 고정 예측기(10-14)와 Optimum(15) 모두에 대한 적합 동작이므로, 작성기의 태그 편차는 허용됩니다.

검증 계층화

매개변수 검증은 설계상 두 계층에서 실행됩니다. DecodeParms는 파싱 시점의 병목 지점으로, 악의적인 크기를 먼저 거부합니다. PngPredictor::inverse()는 두 번째 계층으로서 자체 검사를 유지합니다: 네 매개변수 모두에 대한 범위 검사, 스트라이드 곱을 형성하기 전에 단일 인자를 PHP_INT_MAX와 비교하는 오버플로 가드, 동일한 64,000,000바이트 행당 상한, 그리고 어떤 행 버퍼도 할당되기 전에 전체 입력보다 큰 선언된 스트라이드를 거부하는 입력 비례 경계입니다.

결정성

두 진입점 모두 입력의 순수 정적 함수입니다. I/O도, 로깅도, 전역 상태도 없습니다. 실행 시간은 입력 길이에 선형이며 작은 바이트당 상수를 가집니다. /DecodeParms 파싱은 몇 개의 경계된 정규식 매칭입니다. 예산은 프론트매터 performance_budget에 명시되어 있습니다.

엣지 케이스 및 실패 모드

이 모듈의 모든 실패는 문제가 된 값을 메시지에 명시하며 InvalidArgumentException을 발생시킵니다.

• fromDictionary()는 인식된 키에 대한 음수 값이 존재하면 거부합니다.
• fromDictionary()는 /Columns가 1,000,000을 초과하거나 /Colors가 32를 초과하면 거부합니다.
• fromDictionary()는 /BitsPerComponent가 {1, 2, 4, 8, 16} 밖이거나 도출된 행 스트라이드가 64,000,000바이트를 초과하면 거부합니다.
• inverse()는 10-15 밖의 예측기를 거부합니다. TIFF 예측기(2)는 여기서 결코 역필터링되지 않으므로, 먼저 isPngPredictor()로 분기하십시오.
• inverse()는 columns 또는 colors가 1 미만이거나 bitsPerComponent가 허용 집합 밖이면 거부합니다.
• inverse()는 스트라이드 곱이 플랫폼 정수를 오버플로할 기하값을 어떠한 할당보다 먼저 거부합니다.
• inverse()는 실제 입력 길이와 무관하게, 64,000,000바이트 행당 상한을 초과하는 행 스트라이드를 거부합니다.
• inverse()는 빈 입력에 대해 빈 문자열을 반환합니다. 이는 오류가 아닙니다.
• inverse()는 전체 입력보다 큰 선언된 행 스트라이드를 오프셋 0의 잘린 행으로 처리하여 실패합니다.
• inverse()는 후행 부분 행을 잘린 행으로 처리하여, 오프셋과 바이트 수를 명시하며 실패합니다.
• inverse()는 알 수 없는 행별 필터 태그(0-4가 아님)를 태그 값과 행 오프셋과 함께 실패 처리합니다.
• 선언된 /DecodeParms 기하값과 실제 스트림 레이아웃의 불일치는 매개변수 또는 절단 오류로 드러나며, 결코 조용히 손상된 출력으로 나타나지 않습니다.
• Average 필터는 PNG 사양의 floor 의미론에 맞춰 정수 나눗셈을 사용합니다.
• 이 모듈에서는 어떠한 암호화 연산도 발생하지 않습니다. FIPS 제약 배포 환경에서도 동작은 동일합니다.

적합성

Claim	Standard	Clause
/Predictor 필터 매개변수는 예측기 알고리즘을 선택하며, 허용 값은 예측기 값 테이블에서 나옵니다.	ISO 32000-2:2020	§7.4.4.4
PDF는 두 예측기 그룹을 정의합니다: TIFF 그룹은 단일 Predictor 2 함수이고, PNG 그룹은 태그 10-15입니다.	ISO 32000-2:2020	§7.4.4.4
/BitsPerComponent의 유효 값은 1, 2, 4, 8, 16이며 기본값은 8이고, /Colors는 1 이상이며 기본값은 1이고, /Columns의 기본값은 1입니다.	ISO 32000-2:2020	§7.4.4.4
필터 유형 0-4의 재구성 함수는 256을 법으로 바이트 단위로 작동하며, 없는 왼쪽 및 이전 행 바이트는 0으로 읽힙니다.	W3C PNG (Third Edition)	§9.2
Paeth 필터 유형은 왼쪽, 위, 좌상단 이웃의 PaethPredictor를 계산하여 가장 가까운 값을 선택합니다.	W3C PNG (Third Edition)	§9.4

모든 조항은 의역된 것이며, NextPDF는 규범적 텍스트를 재현하지 않습니다. 이는 기능 진술이지 인증이 아니며, NextPDF는 어떤 인증도 보유하지 않고 어떤 인증도 부여하지 않습니다. 재구성 연산과 매개변수 기본값의 적합성은 단위 테스트 스위트로 검증됩니다. 완전한 PDF 스트림 필터 프레임워크와 TIFF 예측기의 역변환은 이 모듈의 범위 밖입니다.

개발 노트

• 두 클래스 모두 nextpdf/pro 3.0.0부터 출시되었으며 3.1.0에서 현행입니다.
• 이 모듈은 입력에 예측기가 포함된 경우 Pro Diff 및 Classifier 추출기에서 사용됩니다.
• inverse()를 호출하기 전에 isPngPredictor()로 분기하십시오. 예측기 1과 TIFF 예측기는 PNG 역변환이 필요 없습니다.
• 이 모듈은 자체 행당 할당을 제한합니다. 신뢰할 수 없는 스트림에서 예측기를 역변환하는 호출자는 Pro 추출기가 그러하듯 상류에서 압축 해제된 입력 크기도 여전히 제한해야 합니다.
• 고정 예측기(10-14)와 Optimum(15)은 하나의 코드 경로를 공유하며, 두 경우 모두 행별 태그가 재구성을 구동합니다.
• 내부 메커니즘 세부 사항은 소스 저장소의 내부 문서에 남으며 이 매뉴얼의 범위 밖입니다.

게시 경계

이 페이지는 외부에서 관찰 가능한 동작과 지원되는 공개 API 표면만을 문서화합니다. 내부 네임스페이스 경로, 헬퍼 클래스, 메커니즘 테이블, 런북 파일명, 티켓 접두사는 범위 밖입니다.

함께 보기

• Filter (기능) — 설치, 빠른 시작, 프로덕션 사용 샘플.
• Diff — 심층 참조 — 역필터의 소비자.
• Classifier — 심층 참조 — 역필터의 소비자.