Pro エディション

NextPDF\Pro\Toc は、HTML から H1–H6 の見出しを収集し、ページ分割された複数レベルの目次を PDF コンテンツストリーム演算子としてレンダリングします。ページ番号は呼び出し元が供給します（または順次プレースホルダー）。このモジュールは、ライブのドキュメント相互参照を解決しません。

提供状況とライセンス

この機能は NextPDF Pro（nextpdf/pro）で提供され、Pro ティアのライセンスエンベロープでアクティブ化されます。そのエンタイトルメントを持たないデプロイメントでは、この機能のクラスは読み込まれません。Toc クラスは、nextpdf/pro がインストールされていればいつでも読み込まれます。このモジュールをゲートするランタイムのケーパビリティフラグはありません。エディションを比較してライセンスを取得。

インストール

composer require nextpdf/pro:^3

概念の概要

ワークフローには 2 つのフェーズがあります:

Collection. AutoTocCollector::extract($html, maxDepth) は、深さ制限までの <h1>–<h6> タグを HTML からスキャンし、内部マークアップを除去し、エンティティをデコードし、空白を正規化し、TocHeading 値オブジェクト（レベル 0 = H1）を出力します。順次ページ番号を割り当てることも、呼び出し元が提供するインデックスからページへのマップを適用することもできます。
Rendering. AutoTocRenderer::render($headings, $config) は、TOC ページごとに 1 つの PDF コンテンツストリーム文字列を生成し、レベルごとのインデント、オプションのドットリーダー、オプションのページ番号を伴います。表示される各行は、ISO 32000-2:2020 §9.4 に従って Tj テキスト表示操作として出力されます。

AutoTocConfig は、タイトル、深さ、フォント、間隔、マージン、色、ページサイズ、そしてドットリーダーとページ番号を表示するかどうかを制御する、イミュータブルでフルエントに設定される値オブジェクトです。

なぜこの仕組みなのか

この設計の要となる決定は、モジュールが知り得ないページ番号を決して捏造しないという点です。真のターゲットページは最終的にレイアウトされたドキュメントに依存し、それは呼び出し元が所有します。推測は、ページ分割が変わるたびに静かにずれてしまいます。そのため、収集とレンダリングはレイアウトから切り離されたままです。AutoTocCollector は、null またはプレースホルダーのページを持つ見出しを出力します。実際のページ番号は、呼び出し元が供給する assignPageNumbers() マップを通じてのみ到着します。レンダリングはその後、プレーンなコンテンツストリーム演算子を生成し、ページ配置を呼び出し元に委ねます。その結果、モジュールは決定的かつ誠実であり続けます。捏造するのではなく、知らないことを明言するのです。

設計背景: 推測を拒む API。

挙動コントラクト

Input. HTML（収集）と TocHeading のリスト（レンダリング）。
Output. 収集からの list<TocHeading>、レンダリングからの PDF コンテンツストリーム演算子の list<string>（TOC ページごとに 1 つ）。
Page numbers. 順次割り当てられるか、インデックスからページへのマップで供給されるか、または null のまま残されます。このモジュールは、レイアウト済みのドキュメントから真のターゲットページを計算しません。相互参照を解決しません。
Depth. maxDepth は 1–6 にクランプされます。設定された深さより深い見出しはスキップされます。
Determinism. 同一の HTML と設定に対しては、収集される見出しとレンダリングされる演算子は安定しています。

公開 API サーフェス

Type	Kind	Key members
`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 はコレクターと config の両方で 1–6 にクランプされます。範囲外の値は、拒否されるのではなく修正されます。
呼び出し元が実際のマップを供給しない限り、ページ番号はプレースホルダーです。このモジュールは、真のターゲットページを発見するためのレイアウトパスを実行しません。
レンダラーは、ページへの配置のためのコンテンツストリーム演算子を出力します。それらのページをドキュメントに追加する責務は呼び出し元にあります。

パフォーマンス

収集は HTML に対する 1 回の正規表現パスです。レンダリングは見出し数に対して線形であり、entriesPerPage() によってページ分割されます。performance_budget を参照してください。

セキュリティに関する注意

HTML は、境界付きの見出し正規表現とタグ除去でスキャンされます。HTML は実行されず、外部参照も辿られません。レンダリングされるテキストは、コンテンツストリーム文字列構文向けにエスケープされます。

適合性

Claim	Spec clause	Status
TOC 行が `Tj` テキスト表示操作として出力される	ISO 32000-2:2020 §9.4	検証済み（ユニットスイート）
ライブのドキュメント相互参照の解決	—	非サポート（呼び出し元供給のページ番号）

Core のフォールバック/代替手段

Core の TOC ジェネレーターはありません。見出しのソース HTML は通常、Core の HTML パイプラインから得られます。/modules/core/html/ を参照してください。

Enterprise の境界に関する注記

このモジュールは見出しを収集し、TOC 演算子をレンダリングします。ドキュメント全体の相互参照の解決、索引生成、ブックマークツリーの同期は行いません。それらの関心事は対象外です。

公開の境界

このページは、外部から観測可能な挙動とサポートされるパブリック API サーフェスのみを記述しています。内部の名前空間パス、ヘルパークラス、メカニズムの表、Runbook のファイル名、チケットのプレフィックスは対象外です。