Pro 에디션

Merge

한눈에 보기

NextPDF\Pro\Merge\SmartMerger는 여러 PDF를 하나로 병합한 뒤 Pro 향상 기능을 적용합니다. 즉, 입력별 레이블로부터 통합된 북마크 트리, 콘텐츠 해시 페이지 중복 제거, 입력별 페이지 범위 선택입니다. 기본 문서 조립은 Pro 객체 그래프 병합 엔진을 통해 실행됩니다. 이는 모든 입력을 하나의 객체 공간으로 다시 번호를 매기고 실제 교차 참조 테이블을 작성합니다.

사용 가능 여부 및 라이선스

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

Merge 클래스는 Pro 패키지가 설치되어 있으면 언제든 사용할 수 있습니다. 이 모듈을 게이트하는 런타임 기능 플래그는 없습니다.

설치

composer require nextpdf/pro:^3

개념 개요

SmartMerger는 MergeInput 값 객체 목록을 받습니다. 각 입력은 소스 PDF 바이트, 선택적 페이지 범위 목록, 그리고 선택적 레이블을 담습니다. 페이지 범위가 있는 입력은 병합 전에 선택된 페이지로 축소됩니다. 결합된 문서는 Pro 객체 그래프 병합 엔진이 생성하며, 이는 모든 입력을 하나의 연속된 객체 공간으로 다시 번호를 매기고 실제 교차 참조 테이블을 내보냅니다. 그런 다음 Pro 레이어가 요청된 향상 기능을 추가합니다.

SmartMergeConfig가 향상 기능을 제어합니다.

북마크 통합은 레이블이 지정된 입력마다 하나의 개요 항목을 삽입하며, 해당 입력 섹션의 시작을 가리킵니다. 이는 ISO 32000-2:2020 §7.7.2의 문서 카탈로그 /Outlines 모델을 따릅니다.
페이지 중복 제거는 입력 전반에 걸쳐 바이트가 동일한 중복 페이지를 콘텐츠 해시로 비교해 제거합니다.
링크 재작성은 병합된 출력에서 내부 GoTo 액션을 스캔합니다.

SmartMergeResult는 병합된 바이트와 함께 통계를 보고합니다. 즉, 총 페이지, 소스 수, 출력 크기, 추가된 북마크, 제거된 중복, 감지된 링크, 그리고 정렬된 입력 레이블입니다.

이렇게 작동하는 이유

PDF 병합은 바이트 연결이 아닙니다. 각 입력은 자체 객체 번호, 교차 참조 테이블, 페이지 트리를 담고 있으므로 단순한 이어붙이기는 어떤 적합한 리더에서도 로드되지 않습니다. 따라서 SmartMerger는 기본 조립을 Pro 객체 그래프 엔진(PdfSplitter::mergeDocuments())에 위임하며, 이는 모든 입력을 하나의 연속된 객체 공간으로 다시 번호를 매기고, 단일 페이지 트리를 재구축하며, 실제 바이트 오프셋을 가진 실제 교차 참조 테이블을 내보냅니다. Pro 향상 기능 — 북마크 통합, 중복 제거, 링크 감지 — 는 조립을 다시 구현하지 않고 검증된 그 출력 위에 계층화됩니다. 전체 문서 중복 제거와 감지 전용 링크 처리는 병합을 결정적이고 신뢰할 수 없는 입력에서도 안전하게 유지하는 의도적인 범위 경계입니다.

설계 배경: PDF 파일의 해부학.

동작 계약

입력. 비어 있지 않은 MergeInput 목록. 빈 목록은 InvalidArgumentException을 발생시킵니다. 입력 수와 입력별 바이트 크기는 SmartMergeConfig(maxInputs, maxBytesPerInput)로 제한됩니다.
출력. SmartMergeResult. 출력이 %PDF 헤더로 시작하면 isValid()가 true입니다.
북마크 통합은 consolidateBookmarks가 활성화되어 있을 때, 비어 있지 않은 레이블을 가진 입력마다 하나의 항목을 추가합니다.
중복 제거는 옵트인(deduplicatePages, 기본 꺼짐)이며 시각적으로 유사한 페이지가 아니라 콘텐츠 해시로 전체 페이지를 매칭합니다.
링크 재작성은 현재 릴리스에서 내부 GoTo 액션을 감지하고 셉니다. 전체 교차 문서 대상 재해석을 수행하지는 않습니다. linksRewritten을 감지 횟수로 취급하십시오.
결정성. 동일한 입력과 구성에 대해 병합된 바이트 스트림은 안정적이며, Pro 병합 엔진의 문서화된 결정성 프로파일을 따릅니다.

공개 API 표면

타입	종류	주요 멤버
`NextPDF\Pro\Merge\SmartMerger`	`final class`	`__construct(?PdfMerger $coreMerger = null, ?PdfSplitter $splitter = null)`, `merge(array $inputs, SmartMergeConfig $config = new SmartMergeConfig()): SmartMergeResult`
`NextPDF\Pro\Merge\MergeInput`	`final readonly class`	`__construct(string $pdfData, array $pageRanges = [], string $label = '')`, `hasPageRanges(): bool`
`NextPDF\Pro\Merge\SmartMergeConfig`	`final readonly class`	`__construct(bool $consolidateBookmarks = true, bool $deduplicatePages = false, bool $rewriteLinks = true, int $maxInputs = 100, int $maxBytesPerInput = 100_000_000)`, `default()`, `basic()`
`NextPDF\Pro\Merge\SmartMergeResult`	`final readonly class`	`string $pdfData`, `int $totalPages`, `int $sourceCount`, `int $bookmarksAdded`, `int $duplicatesRemoved`, `int $linksRewritten`, `array $inputLabels`, `isValid(): bool`, `hasOptimizations(): bool`

코드 샘플 — 빠른 시작

<?php

declare(strict_types=1);

use NextPDF\Pro\Merge\MergeInput;
use NextPDF\Pro\Merge\SmartMerger;

$result = (new SmartMerger())->merge([
    new MergeInput(file_get_contents('cover.pdf'), label: 'Cover'),
    new MergeInput(file_get_contents('body.pdf'),  label: 'Body'),
]);

echo $result->totalPages, " pages, ",
     $result->bookmarksAdded, " bookmarks\n";

코드 샘플 — 프로덕션

<?php

declare(strict_types=1);

use NextPDF\Pro\Merge\MergeInput;
use NextPDF\Pro\Merge\SmartMergeConfig;
use NextPDF\Pro\Merge\SmartMerger;

function assemblePacket(array $sections): string
{
    $inputs = [];
    foreach ($sections as $label => $bytes) {
        $inputs[] = new MergeInput($bytes, label: (string) $label);
    }

    $config = new SmartMergeConfig(
        consolidateBookmarks: true,
        deduplicatePages: true,
        rewriteLinks: false,
        maxInputs: 50,
    );

    $result = (new SmartMerger())->merge($inputs, $config);

    if (! $result->isValid()) {
        throw new RuntimeException('merge produced invalid output');
    }

    return $result->pdfData;
}

엣지 케이스 및 함정

단일 입력도 유효하며, 해당 문서의 정규화된 복사본으로 병합됩니다.
중복 제거는 전체 페이지 바이트 콘텐츠를 비교합니다. 메타데이터나 객체 번호만 다른 페이지는 중복으로 취급되지 않습니다.
입력에 대한 페이지 범위 선택은 병합 순서 지정 전에 적용됩니다.
linksRewritten은 감지된 액션 수이며, 모든 교차 문서 링크 대상이 다시 지정되었다는 보장이 아닙니다.

성능

비용은 Pro 병합 엔진이 좌우하며, 총 입력 바이트와 페이지 수에 따라 확장됩니다. 중복 제거는 페이지마다 콘텐츠 해시 하나를 추가합니다. performance_budget 프런트매터가 병합당 참조입니다.

보안 참고

입력 수와 입력별 크기는 적대적 입력으로 인한 리소스 고갈을 제한하기 위해 SmartMergeConfig로 제한됩니다. 병합은 포함된 문서 스크립트를 실행하지 않습니다. 바이트 스트림 파싱 강화에 대해서는 Core 보안 모델을 참조하십시오.

적합성

주장	사양 조항	상태
`/Outlines`를 통한 통합 북마크	ISO 32000-2:2020 §7.7.2	검증됨 (단위 스위트)
콘텐츠 해시 페이지 중복 제거	—	검증됨 (단위 스위트)
전체 교차 문서 링크 재해석	—	미지원 (감지만)

Core 폴백 / 대안

Pro 통합 없이 기본 연결을 하려면 오픈 소스 Core NextPDF\Document\PdfMerger가 지원되는 독립 실행 경로입니다. SmartMerger는 이를 위임하지 않습니다. Pro 병합은 자체 객체 그래프 엔진에서 실행됩니다. /modules/core/document/를 참조하십시오.

Enterprise 경계 참고

이 모듈은 구조적 병합을 수행합니다. 법적 보존 조립, 수정(redaction), 또는 증거적 보관 연쇄(chain-of-custody) 패키징을 수행하지 않습니다. 그러한 기능은 여기에서 제공되지 않습니다.

게시 경계

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