Pro 에디션

Projection

한눈에 보기

Projection은 PDF 콘텐츠 스트림을 평면 토큰 목록으로 파싱하고 그 토큰으로부터 새 콘텐츠 스트림을 방출합니다. 방출에는 명시적으로 선언된 의도가 필요합니다. 이 모듈은 범용 PDF 편집기가 아닙니다.

참고. 여기서 “Projection”은 콘텐츠 스트림 토큰 프로젝션을 의미합니다. 좌표 또는 지리 공간 프로젝션이 아닙니다. 지리 공간 기능은 Geo 모듈을 참조하십시오.

가용성 및 라이선스

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

별도의 기능별 라이선스 플래그는 없습니다. 필수 ProjectionIntent 인수가 라이선스 스위치가 아니라 API 수준에서 방출을 게이트합니다.

설치

composer require nextpdf/pro:^3

코드는 NextPDF\Pro\Projection 네임스페이스 아래에 있습니다.

개념 개요

ContentProjectionWriter는 세 가지 정적 작업을 제공합니다.

tokenize()는 콘텐츠 스트림을 평면적이고 순서가 있는 토큰 목록으로 파싱합니다. 이는 읽기 전용이며 의도가 필요하지 않습니다.
emit()는 (가능하면 수정된) 토큰 목록으로부터 새 콘텐츠 스트림을 작성합니다. 이는 ProjectionIntent를 요구합니다.
roundTrip()은 검증을 위해 변경 없이 토큰화한 뒤 다시 방출합니다.

출력은 개념적으로 원본의 편집된 복사본이 아니라 새 콘텐츠 스트림입니다. 방출기는 공백과 주석을 정규화하지만 연산자 시퀀스와 피연산자 값을 정확하게 유지합니다. 의도 enum은 정확히 두 가지 경우 — 정화(sanitization, redaction)와 스테가노그래피 임베딩 — 를 가지며, 정적 분석이 의도하지 않은 사용을 감지할 수 있도록 의도적으로 일반 경우를 두지 않습니다.

이렇게 동작하는 이유

Projection은 범용 PDF 편집기가 되기를 거부합니다. 방출은 평면 토큰 목록으로부터 새로운 콘텐츠 스트림을 다시 빌드하므로 원본은 결코 제자리에서 변경되지 않습니다. 이 단방향 모델이 redaction을 신뢰할 수 있게 만드는 요소입니다. 제거된 토큰은 덧칠되는 것이 아니라 출력에서 아예 존재하지 않습니다. 그렇기 때문에 emit()은 명시적 ProjectionIntent를 요구하며, enum은 정화와 스테가노그래피 임베딩만 제공하고 일반 경우는 없습니다. 그러면 정적 분석이 선언되고 알려진 목적이 없는 방출을 모두 표시할 수 있습니다. 이 설계는 편집의 편의성을 파괴적 의도가 항상 호출 지점에서 보이도록 하는 보장과 맞바꿉니다.

설계 배경: Redaction is not a black rectangle.

동작 계약

tokenize($contentStream)는 문자열, 이름, 숫자, 배열, 딕셔너리, 부울, null, 연산자를 포괄하는 토큰 목록을 반환합니다.
emit($tokens, $intent)는 명시적 의도를 요구합니다. 타입 시스템이 호출 지점에서 이를 강제합니다.
roundTrip() 출력은 입력과 바이트가 동일하지는 않지만, 연산자 시퀀스와 피연산자 값은 일치합니다.
방출기는 정수와 부동소수점 구분을 유지하도록 숫자를 포맷하고 리터럴 문자열을 다시 이스케이프합니다.
두 선언된 의도는 정화(파괴적이고 되돌릴 수 없는 redaction 작업)와 스테가노그래피 임베딩입니다.

코드 샘플 — 빠른 시작

다음은 문서화된 공개 API를 반영합니다. 리포지터리는 이 모듈에 대한 실행 가능한 예제를 제공하지 않습니다.

use NextPDF\Pro\Projection\ContentProjectionWriter;

$tokens = ContentProjectionWriter::tokenize($contentStream);

코드 샘플 — 프로덕션

use NextPDF\Pro\Projection\ContentProjectionWriter;
use NextPDF\Pro\Projection\ProjectionIntent;

$tokens = ContentProjectionWriter::tokenize($contentStream);

// Validate first: a clean round-trip must hold before any modification.
$check = ContentProjectionWriter::roundTrip($contentStream);

// Apply your modification to $tokens, then emit with a declared intent.
$output = ContentProjectionWriter::emit($tokens, ProjectionIntent::Sanitization);

엣지 케이스 및 함정

수정 후 방출 시퀀스를 신뢰하기 전에 roundTrip()을 실행하고 그것이 유지되는지 확인하십시오. 실패하는 라운드 트립을 중지 조건으로 취급하십시오.
정화 의도는 되돌릴 수 없습니다. 제거된 콘텐츠는 출력에서 복구할 수 없습니다.
방출기는 공백을 정규화하고 주석을 제거하므로, 수정되지 않은 라운드 트립이라도 원본과의 바이트 수준 비교는 차이가 납니다.

성능

토큰화와 방출은 콘텐츠 스트림 길이에 선형적입니다. 토큰화기는 8진수 이스케이프 읽기와 16진수 문자열 처리를 제한합니다. 발행된 처리량 수치는 없습니다. 대표적인 콘텐츠 스트림으로 측정하십시오.

보안 참고

필수 의도 인수는 범용 편집기로서의 오용을 방지합니다. 정화 의도는 파괴적이고 되돌릴 수 없습니다. 배포 전에 먼저 라운드 트립을 검증하고 redaction된 출력을 확인하십시오. 이 모듈은 콘텐츠를 로깅하지 않습니다.

적합성

토큰화는 ISO 32000-2의 어휘 및 콘텐츠 스트림 관례를 따릅니다. 소스가 관련 조항을 주석으로 표시합니다. 작성 시점에 RAG 코퍼스를 사용할 수 없었으므로, 이 페이지는 외부 조항 식별자를 주장하지 않으며 적합성 진술을 모듈 테스트로 검증된 동작으로 한정합니다.

Enterprise 경계 참고

Enterprise는 Projection 동작을 변경하지 않습니다. Enterprise는 별도로 문서화된 상위 계층의 개인 정보 및 규정 준수 기능을 추가합니다. 이는 projection API를 사용하는 데 필요하지 않습니다.

Core 폴백 / 대안

Core 등가물은 없습니다. Pro 없이는 호출자가 자체 콘텐츠 스트림 토큰화기를 빌드해야 합니다. 의도 게이트된 프로젝션 모델은 Pro 전용 추가 기능입니다.

발행 경계

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