AST

한눈에 보기

AST 모듈은 PDF를 불변의 탐색 가능한 문서 트리로 변환합니다. 태그된 구조 트리가 있으면 이를 사용하고, 태그되지 않은 문서에 대해서는 휴리스틱 빌더로 폴백하며, 각 노드에 바운딩 박스와 텍스트를 첨부합니다.

가용성 및 라이선싱

이 기능은 NextPDF Pro(nextpdf/pro)로 제공되며 Pro 등급 라이선스 봉투로 활성화됩니다. 해당 권한이 없는 배포는 이 기능의 클래스를 로드하지 않습니다. 에디션을 비교하고 라이선스를 받으십시오.

기능별 라이선스 플래그는 존재하지 않습니다. 코드는 Pro 에디션과 함께 제공되며, 빌드 동작은 라이선스 스위치가 아니라 전적으로 AstBuildOptions(리소스 한도 및 페이지 범위)에 의해 관장됩니다.

설치

composer require nextpdf/pro:^3

코드는 NextPDF\Pro\Ast 네임스페이스 아래에 존재합니다.

개념 개요

AstBuilder는 PDF-투-트리 파이프라인을 조율합니다. 즉, 캐시를 확인하고, 암호화된 입력을 일찍 거부하고, 태그된 PDF에 대해 구조 트리를 읽고, 그렇지 않으면 태그되지 않은 경로로 폴백하고, 콘텐츠 스트림 분석으로부터 바운딩 박스를 첨부한 다음, 결과를 캐시합니다. 출력은 노드가 불변인 AstDocument입니다. 업데이트는 제자리에서 변경하는 대신 영향받는 하위 트리를 상향식(bottom-up)으로 재구성합니다.

태그되지 않은 PDF에 대해 두 가지 폴백 전략이 존재합니다. 즉, 단순(bare) 폴백과 선택적 휴리스틱 빌더(AstBuildOptions::$useHeuristic)입니다. 이 모듈은 또한 AST를 PDF로 다시 기록하고 결과를 검증할 수 있는 이미터(emitter) 경로와, 트리에 적용된 변경을 추적하기 위한 변경 로그를 제공합니다.

이렇게 작동하는 이유

트리는 구성상 불변입니다. 각 편집은 영향받는 루트-투-노드 경로만 재구축하고 변경되지 않은 하위 트리를 동일성(identity)으로 공유하므로, 빌드된 AstDocument는 방어적 복사 없이도 보유하고, 캐시하고, 동시 판독자에게 넘겨도 안전합니다. 이는 PDF 자체가 디스크에서 변경되는 방식을 그대로 반영합니다. 라이트백 경로는 파일을 다시 쓰지 않고 AstWriter를 통해 증분 업데이트를 추가하여 원본 바이트 — 그리고 기존 서명 — 을 그대로 유지합니다. 추가 전용(append-only) 리비전은 구조적으로 검증하기도 저렴하며, 이것이 AstWriter가 반환하기 전에 자기 자신의 출력을 검사할 수 있는 이유입니다. 제자리에서 변경하는 대신 하위 트리를 재구성하는 것이 이 모듈을 탐색 가능하면서도 안전하게 편집 가능하게 만드는 유일한 결정입니다.

설계 배경: 증분 업데이트와 그것이 중요한 이유.

동작 계약

• AstBuilder::build($sourceHash)는 소스 PDF의 전체 SHA-256 16진수를 받아 AstDocument를 반환합니다.
• 암호화된 PDF는 전용 미지원 암호화 오류로 거부됩니다. 빌드 전에 복호화하십시오.
• 구조 트리가 없으면 빌더는 자동으로 태그되지 않은 경로를 사용합니다 — 활성화되어 있으면 휴리스틱, 그렇지 않으면 단순 폴백입니다.
• AstBuildOptions의 리소스 한도(최대 노드, 최대 깊이, 최대 메모리, 벽시계 타임아웃)는 무한정 작업 대신 빌드 한도 또는 빌드 타임아웃 오류를 유발합니다.
• 캐시 키는 소스 해시와 옵션 해시를 통합하므로, 동일한 입력과 옵션을 가진 두 빌드는 동일한 트리를 반환합니다.
• AstNode는 불변입니다. 소비자는 트리가 변경될 때 새로운 노드 인스턴스를 받습니다.

코드 샘플 — 빠른 시작

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

use NextPDF\Pro\Ast\AstBuilder;
use NextPDF\Pro\Ast\AstBuildOptions;

$builder = new AstBuilder($pdfReader, new AstBuildOptions());
$document = $builder->build($sha256OfPdf);

코드 샘플 — 프로덕션

use NextPDF\Pro\Ast\AstBuilder;
use NextPDF\Pro\Ast\AstBuildOptions;

$options = new AstBuildOptions(
    maxNodes: 100_000,
    maxDepth: 200,
    maxMemoryBytes: 256 * 1024 * 1024,
    timeoutSeconds: 30.0,
    useHeuristic: true,
);

$builder = new AstBuilder($pdfReader, $options, $astCache);

try {
    $document = $builder->build($sha256OfPdf);
} catch (\NextPDF\Pro\Ast\Exception\AstUnsupportedEncryptionException $e) {
    // Decrypt the source first, then retry.
}

엣지 케이스 및 주의 사항

• 콘텐츠 스트림을 파싱할 수 없는 페이지는 바운딩 박스 첨부 중에 건너뜁니다. 트리는 여전히 반환되며, 다만 해당 페이지에 대한 박스가 없을 뿐입니다.
• 휴리스틱 빌더는 옵트인입니다. 비활성화하면 태그되지 않은 PDF는 단순 폴백으로부터 더 거친 트리를 산출합니다.
• AstBuildOptions의 페이지 범위는 0 기반의 포함(inclusive) 인덱스를 사용합니다. 두 경계를 모두 null로 두면 모든 페이지를 처리합니다.

성능

빌드 비용은 노드 수와 페이지 수에 따라 확장됩니다. AstBuildOptions가 둘 다 한정합니다. 캐시는 동일한 옵션으로 동일한 입력을 반복 빌드하는 것을 단락(short-circuit)합니다. NextPDF는 여기에 고정된 문서당 타이밍을 발행하지 않습니다. 벽시계 타임아웃(기본 30 s)과 노드 상한(기본 100,000)이 최악의 작업을 한정합니다. 대표적인 문서로 측정하십시오.

보안 참고 사항

입력을 신뢰할 수 없는 것으로 취급하십시오. 빌더는 암호화된 PDF를 부분 처리하는 대신 거부합니다. 리소스 상한(노드, 깊이, 메모리, 시간)은 병리적이거나 적대적인 문서로부터 보호합니다. 이 모듈은 어떤 문서 콘텐츠도 로그에 기록하지 않습니다.

적합성

구조 트리 경로는 ISO 32000-2가 정의하는 태그된 PDF 구조를 읽습니다. 모듈의 소스는 관련 콘텐츠 스트림 및 구조 조항에 주석을 답니다. 작성 시점에 RAG 코퍼스를 사용할 수 없었으므로, 이 페이지는 어떠한 외부 조항 식별자도 주장하지 않으며 적합성 진술을 모듈의 테스트로 검증된 동작으로 한정합니다.

Enterprise 경계 참고

Enterprise는 AST 동작을 변경하지 않습니다. Enterprise는 별도로 문서화된 상위 등급의 규정 준수 및 아카이브 역량을 추가합니다. 그것들은 AST를 빌드하거나 소비하는 데 필요하지 않습니다.

Core 폴백 / 대안

Pro 없이는 동등한 문서 트리가 없습니다. 호출자는 NextPDF Core 프리미티브를 사용하여 콘텐츠 스트림을 직접 파싱합니다. /modules/ast/를 참조하십시오.

게시 경계

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

함께 보기

• AST — Deep Reference
• Projection
• Diff
• Output Pipeline