Pro 에디션

Document

한눈에 보기

Document 모듈은 PDF를 페이지 범위별로 세그먼트로 분할하고, 정렬 가능한 스키마 열을 갖춘 PDF Portfolio(Collection)를 조립합니다. 두 작업 모두 적대적 입력에 대해 경계가 지정되어 있습니다.

제공 및 라이선스

이 기능은 NextPDF Pro(nextpdf/pro)에 포함되어 제공되며, Pro 등급 라이선스 봉투로 활성화됩니다. 해당 자격이 없는 배포는 이 기능의 클래스를 로드하지 않습니다. Document는 Pro 에디션의 일부이며, 기능별 별도의 라이선스 플래그는 없습니다. 에디션 비교 및 라이선스 받기.

설치

composer require nextpdf/pro:^3

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

개념 개요

두 가지 기능이 제공됩니다.

PdfSplitter는 페이지 범위를 독립형 PDF 세그먼트로 추출합니다. 원시 입력에서 페이지 객체를 스캔하여 페이지를 탐지하고, 선택된 페이지를 최소 카탈로그 및 페이지 트리로 감쌉니다. 범위 기반 분할, 고정 크기 분할(splitEvery), 단일 범위 추출(extractPages)을 지원합니다.
PdfPortfolio는 정의된 스키마로 파일 첨부를 집계하는 PDF Collection 딕셔너리를 빌드합니다. 타일, 디테일, 숨김 보기 모드를 지원하며 문서 카탈로그에 포함하기에 적합한 딕셔너리를 방출합니다.

이렇게 동작하는 이유

PDF 분할은 바이트 슬라이스가 아닙니다. 페이지 객체는 공유 리소스, 폰트, 콘텐츠 스트림을 간접 참조로 가리킵니다. 또한 페이지 트리 조상으로부터 /MediaBox와 /Resources를 상속합니다. 따라서 분할기는 각 세그먼트를 자기완결적 객체 그래프로 재구성합니다. 선택된 페이지의 전이적 참조 폐포를 순회하고, 상속된 속성을 실체화하며, 새로운 id 공간으로 재번호를 매기고, 바이트 단위로 정확한 오프셋을 갖는 상호 참조 테이블을 씁니다. 폐포 순회는 경계가 지정되어 있는데, 그렇지 않으면 적대적인 팬아웃 그래프가 하나의 세그먼트로 무한한 작업을 끌어들일 수 있기 때문입니다. 그 결과는 매달린 참조를 가진 조각이 아니라 유효한 독립형 PDF로 열립니다.

설계 배경: The anatomy of a PDF file.

동작 계약

PdfSplitter::split($pdfData, $ranges, $maxBytes = 100_000_000, $maxRanges = 1000)은 입력 크기 제한과 범위 수 제한을 적용하며, PDF 헤더로 시작하지 않는 입력을 거부합니다.
splitEvery($pdfData, $pagesPerSegment)은 1 미만의 세그먼트 크기를 거부합니다. 마지막 세그먼트는 더 적은 페이지를 포함할 수 있습니다.
PdfPortfolio는 구성 시점에 타일, 디테일, 숨김 외의 보기 모드를 거부합니다.
addSchema()와 addEntry()는 플루언트 체이닝을 위해 포트폴리오를 반환합니다. generateCollectionDictionary()는 Collection 딕셔너리 문자열을 반환합니다.
스키마 필드 이름은 PDF 이름 객체로 사용하기 위해 살균되며, 문자열 값은 PDF 리터럴 문자열을 위해 이스케이프됩니다.

코드 샘플 — 빠른 시작

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

use NextPDF\Pro\Document\PdfSplitter;
use NextPDF\Document\PageRange;

$result = (new PdfSplitter())->split($pdfBytes, [new PageRange(1, 5)]);

코드 샘플 — 프로덕션

use NextPDF\Pro\Document\PdfSplitter;
use NextPDF\Document\PageRange;

$splitter = new PdfSplitter();

try {
    $result = $splitter->split(
        $pdfBytes,
        [new PageRange(1, 10), new PageRange(11, 20)],
        maxBytes: 50_000_000,
        maxRanges: 100,
    );
} catch (\InvalidArgumentException $e) {
    // Input rejected (not a PDF, or limits exceeded).
}

엣지 케이스 및 함정

분할기는 각 세그먼트를 실제로 바이트 단위 정확한 상호 참조 테이블을 갖춘 새로운 객체 그래프로 재구성하므로, 세그먼트는 유효한 독립형 PDF입니다. 소스 바이트 레이아웃을 보존하는 대신 새로운 id 공간으로 재번호를 매기므로, 증분 업데이트나 서명 워크플로에는 세그먼트 바이트를 Writer 모듈로 넘기십시오.
어떤 페이지와도 일치하지 않는 범위는 오류 대신 최소 한 페이지 세그먼트를 산출합니다.
포트폴리오 정렬은 기본적으로 첫 번째 스키마 필드 기준 오름차순입니다.

성능

분할과 포트폴리오 조립은 입력 크기와 엔트리 수에 선형적입니다. 기본 입력 상한은 100 MB이고 기본 범위 상한은 1000입니다. 둘 다 호출자가 더 낮게 조정할 수 있습니다. 대표적인 문서로 측정하십시오.

보안 참고

입력을 신뢰할 수 없는 것으로 취급하십시오. 크기 및 수 가드가 리소스 사용을 한정합니다. 모듈은 필드 이름이 출력 딕셔너리에 도달하기 전에 이를 살균하고 문자열 값을 이스케이프합니다. 문서 콘텐츠는 로그에 기록하지 않습니다.

적합성

Portfolio 딕셔너리는 PDF Collections 모델을 따르며 분할기는 ISO 32000-2가 정의하는 페이지 객체 모델을 따릅니다. 소스가 관련 조항을 주석으로 표시합니다. 저작 시점에 RAG 코퍼스를 사용할 수 없었으므로, 이 페이지는 외부 조항 식별자를 단언하지 않으며 적합성 진술을 모듈의 테스트로 검증된 동작으로 한정합니다.

Enterprise 경계 참고

Enterprise는 Document 동작을 변경하지 않습니다. Enterprise는 별도로 문서화된 상위 등급 보관 및 규정 준수 기능을 더합니다. 그것들은 분할이나 Portfolio 조립에 필요하지 않습니다.

Core 폴백 / 대안

Pro가 없으면 NextPDF Core의 기본 문서 프리미티브를 사용하십시오. 페이지 범위 분할과 Portfolio 조립은 Pro 추가 기능입니다. /modules/document/를 참조하십시오.

공개 경계

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