Pro 에디션

NextPDF\Pro\Toc는 HTML에서 H1–H6 제목을 수집하고, 페이지네이션된 다단계 목차를 PDF 콘텐츠 스트림 연산자로 렌더링합니다. 페이지 번호는 호출자가 제공합니다(또는 순차 placeholder). 이 모듈은 라이브 문서 상호 참조를 해석하지 않습니다.

가용성 및 라이선스

이 기능은 NextPDF Pro(nextpdf/pro)에 포함되며 Pro 등급 라이선스 봉투로 활성화됩니다. 해당 사용 권한이 없는 배포는 이 기능의 클래스를 로드하지 않습니다. Toc 클래스는 nextpdf/pro가 설치되어 있으면 언제나 로드되며, 런타임 기능 플래그가 이 모듈을 게이팅하지 않습니다. 에디션 비교 및 라이선스 받기.

설치

composer require nextpdf/pro:^3

개념 개요

워크플로에는 두 단계가 있습니다.

수집. AutoTocCollector::extract($html, maxDepth)는 깊이 한계까지 HTML에서 <h1>–<h6> 태그를 스캔하고, 내부 마크업을 제거하고, 엔티티를 디코딩하고, 공백을 정규화하며, TocHeading 값 객체를 방출합니다(레벨 0 = H1). 순차 페이지 번호를 할당하거나 호출자가 제공한 인덱스-페이지 맵을 적용할 수 있습니다.
렌더링. AutoTocRenderer::render($headings, $config)는 TOC 페이지당 하나의 PDF 콘텐츠 스트림 문자열을 생성하며, 레벨별 들여쓰기, 선택적 점 리더(dot leaders), 선택적 페이지 번호를 포함합니다. 보이는 각 줄은 ISO 32000-2:2020 §9.4에 따라 Tj 텍스트 표시 연산으로 방출됩니다.

AutoTocConfig는 제목, 깊이, 글꼴, 간격, 여백, 색상, 페이지 크기, 그리고 점 리더와 페이지 번호 표시 여부를 제어하는 불변의 플루언트하게 구성된 값 객체입니다.

이렇게 동작하는 이유

핵심적인 설계 결정은 모듈이 알 수 없는 페이지 번호를 결코 지어내지 않는다는 것입니다. 실제 대상 페이지는 최종적으로 레이아웃된 문서에 의존하며, 그 문서는 호출자가 소유합니다. 추측은 페이지네이션이 바뀔 때마다 조용히 어긋납니다. 그래서 수집과 렌더링은 레이아웃과 분리된 채로 유지됩니다. AutoTocCollector는 페이지가 null이거나 placeholder인 제목을 방출하며, 실제 페이지 번호는 오직 호출자가 제공한 assignPageNumbers() 맵을 통해서만 도착합니다. 그런 다음 렌더링은 순수한 콘텐츠 스트림 연산자를 생성하고, 페이지 배치는 호출자에게 맡깁니다. 그 결과는 결정적이고 정직하게 유지됩니다. 모듈은 알지 못하는 것을 지어내는 대신 알지 못한다고 밝힙니다.

설계 배경: 추측을 거부하는 API.

동작 계약

입력. HTML(수집)과 TocHeading 목록(렌더링).
출력. 수집에서 list<TocHeading>; 렌더링에서 PDF 콘텐츠 스트림 연산자의 list<string>(TOC 페이지당 하나).
페이지 번호. 순차적으로 할당되거나, 인덱스-페이지 맵을 통해 제공되거나, null로 남습니다. 모듈은 레이아웃된 문서로부터 실제 대상 페이지를 계산하지 않으며, 상호 참조를 해석하지 않습니다.
깊이. maxDepth는 1–6으로 클램핑됩니다. 구성된 깊이보다 깊은 제목은 건너뜁니다.
결정성. 동일한 HTML과 구성에 대해, 수집된 제목과 렌더링된 연산자는 안정적입니다.

공개 API 표면

타입	종류	주요 멤버
`NextPDF\Pro\Toc\AutoTocCollector`	`final class`	`static extract(string $html, int $maxDepth = 6): list<TocHeading>`, `scan(string $html): void`, `assignSequentialPages(int $startPage = 1): list<TocHeading>`, `assignPageNumbers(array $pageMap): list<TocHeading>`
`NextPDF\Pro\Toc\AutoTocRenderer`	`final class`	`static render(array $headings, ?AutoTocConfig $config = null): list<string>`
`NextPDF\Pro\Toc\AutoTocConfig`	`final readonly class`	`default()`, `landscape()`, `letter()`, `withTitle()`, `withMaxDepth()`, `withFontSize()`, `withDotLeader()`, `withPageNumbers()`, `withIndentPerLevel()`, `entriesPerPage(): int`
`NextPDF\Pro\Toc\TocHeading`	`final readonly class`	`string $title`, `int $level`, `?int $pageNumber`, `float $y`, `withPageNumber()`, `withPosition()`, `hasPageNumber(): bool`

코드 샘플 — 빠른 시작

<?php

declare(strict_types=1);

use NextPDF\Pro\Toc\AutoTocCollector;
use NextPDF\Pro\Toc\AutoTocRenderer;

$headings = AutoTocCollector::extract($html, maxDepth: 3);
$streams  = AutoTocRenderer::render($headings);

echo count($streams), " TOC page(s) of content-stream operators\n";

코드 샘플 — 프로덕션

<?php

declare(strict_types=1);

use NextPDF\Pro\Toc\AutoTocCollector;
use NextPDF\Pro\Toc\AutoTocConfig;
use NextPDF\Pro\Toc\AutoTocRenderer;

function buildToc(string $html, array $headingPageMap): array
{
    $collector = new AutoTocCollector(maxDepth: 4);
    $collector->scan($html);

    // Caller supplies real page numbers from its own layout pass.
    $headings = $collector->assignPageNumbers($headingPageMap);

    $config = AutoTocConfig::default()
        ->withTitle('Contents')
        ->withMaxDepth(4)
        ->withDotLeader(true)
        ->withPageNumbers(true);

    return AutoTocRenderer::render($headings, $config);
}

엣지 케이스 및 함정

(태그 제거 후) 빈 제목 텍스트는 건너뜁니다.
maxDepth는 collector와 config 양쪽에서 1–6으로 클램핑됩니다. 범위를 벗어난 값은 거부되는 대신 보정됩니다.
호출자가 실제 맵을 제공하지 않는 한 페이지 번호는 placeholder입니다. 모듈은 실제 대상 페이지를 발견하기 위한 레이아웃 패스를 실행하지 않습니다.
렌더러는 페이지에 배치하기 위한 콘텐츠 스트림 연산자를 방출합니다. 그 페이지를 문서에 추가하는 것은 호출자의 책임입니다.

성능

수집은 HTML에 대한 정규 표현식 패스 1회입니다. 렌더링은 제목 수에 선형적이며, entriesPerPage()로 페이지네이션됩니다. performance_budget을 참고하십시오.

보안 참고

HTML은 한정된 제목 정규 표현식과 태그 제거로 스캔됩니다. 어떤 HTML도 실행되지 않으며 외부 참조도 따르지 않습니다. 렌더링된 텍스트는 콘텐츠 스트림 문자열 구문에 맞게 이스케이프됩니다.

적합성

주장	명세 조항	상태
TOC 줄이 `Tj` 텍스트 표시 연산으로 방출됨	ISO 32000-2:2020 §9.4	검증됨 (단위 스위트)
라이브 문서 상호 참조 해석	—	지원되지 않음 (호출자 제공 페이지 번호)

Core 폴백 / 대안

Core TOC 생성기는 없습니다. 제목 소스 HTML은 일반적으로 Core HTML 파이프라인에서 나옵니다. /modules/core/html/를 참고하십시오.

Enterprise 경계 참고

이 모듈은 제목을 수집하고 TOC 연산자를 렌더링합니다. 문서 전체 상호 참조 해석, 색인 생성, 북마크 트리 동기화는 수행하지 않습니다. 그러한 사안은 범위 밖입니다.

게시 경계

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

목차

한눈에 보기