Pro редакция

NextPDF\Pro\Toc собирает заголовки H1–H6 из HTML и отрисовывает разбитое на страницы, многоуровневое оглавление как операторы потока содержимого PDF. Номера страниц задаются вызывающей стороной (или последовательными плейсхолдерами); модуль не разрешает живые перекрёстные ссылки документа.

Доступность и лицензирование

Эта возможность поставляется в 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) формирует одну строку потока содержимого PDF на каждую страницу оглавления, с отступом по уровню, необязательными точечными выносками и необязательными номерами страниц. Каждая видимая строка эмитируется как операция показа текста Tj согласно ISO 32000-2:2020 §9.4.

AutoTocConfig — это неизменяемый, текуче настраиваемый объект-значение, управляющий заголовком, глубиной, шрифтами, интервалами, полями, цветами, размером страницы и тем, показываются ли точечные выноски и номера страниц.

Почему это работает именно так

Несущее решение состоит в том, что модуль никогда не выдумывает номер страницы, который не может знать. Истинные целевые страницы зависят от финального скомпонованного документа, которым владеет вызывающая сторона; догадка тихо дрейфовала бы всякий раз при изменении разбивки на страницы. Поэтому сбор и отрисовка остаются отделёнными от компоновки. AutoTocCollector эмитирует заголовки с null или плейсхолдерными страницами; реальные номера страниц приходят только через предоставленную вызывающей стороной карту assignPageNumbers(). Отрисовка затем формирует обычные операторы потока содержимого, оставляя размещение страниц вызывающей стороне. Результат остаётся детерминированным и честным: модуль сообщает о том, чего он не знает, вместо того чтобы это фабриковать.

Предыстория проектирования: API, который отказывается угадывать.

Контракт поведения

Вход. HTML (сбор) и список TocHeading (отрисовка).
Выход. list<TocHeading> от сбора; list<string> операторов потока содержимого PDF (по одному на страницу оглавления) от отрисовки.
Номера страниц. Либо назначаются последовательно, либо предоставляются через карту «индекс → страница», либо оставляются 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 зажимается в 1–6 и у коллектора, и в конфигурации; значения вне диапазона корректируются, а не отклоняются.
Номера страниц — это плейсхолдеры, пока вызывающая сторона не предоставит реальную карту; модуль не выполняет прохода компоновки, чтобы обнаружить истинные целевые страницы.
Отрисовщик эмитирует операторы потока содержимого для размещения на странице; вызывающая сторона отвечает за добавление этих страниц в документ.

Производительность

Сбор — это один проход регулярного выражения по HTML. Отрисовка линейна по числу заголовков, разбита на страницы по entriesPerPage(). См. performance_budget.

Замечания по безопасности

HTML сканируется ограниченным регулярным выражением для заголовков и удалением тегов; никакой HTML не исполняется и никакие внешние ссылки не переходят. Отрисованный текст экранируется для синтаксиса строк потока содержимого.

Соответствие

Утверждение	Пункт спецификации	Статус
Строки оглавления эмитируются как операции показа текста `Tj`	ISO 32000-2:2020 §9.4	Проверено (модульный набор)
Разрешение живых перекрёстных ссылок документа	—	Не поддерживается (номера страниц задаются вызывающей стороной)

Резервный режим Core / альтернатива

Генератора оглавления в Core нет. Исходный HTML заголовков обычно приходит из конвейера HTML из Core. См. /modules/core/html/.

Замечание о границе Enterprise

Этот модуль собирает заголовки и отрисовывает операторы оглавления. Он не выполняет разрешения перекрёстных ссылок по всему документу, генерации указателя или синхронизации дерева закладок; эти задачи вне области охвата.

Граница публикации

Эта страница описывает только внешне наблюдаемое поведение и поддерживаемую поверхность публичного API. Внутренние пути пространств имён, вспомогательные классы, таблицы механизмов, имена файлов ранбуков и префиксы тикетов вне области охвата.

Оглавление

Кратко