Pro edisi

Daftar isi

Sekilas pandang

NextPDF\Pro\Toc mengumpulkan heading H1–H6 dari HTML dan merender daftar isi multi-level yang terpaginasi sebagai operator content-stream PDF. Nomor halaman disuplai oleh pemanggil (atau placeholder sekuensial); modul ini tidak menyelesaikan referensi-silang dokumen langsung.

Ketersediaan & lisensi

Kapabilitas ini disertakan dalam NextPDF Pro (nextpdf/pro) dan aktif dengan envelope lisensi tingkat Pro. Deployment tanpa entitlement tersebut tidak memuat kelas-kelas kapabilitas ini. Kelas-kelas Toc dimuat kapan pun nextpdf/pro terpasang; tidak ada flag kapabilitas runtime yang menggerbang modul ini. Bandingkan edisi dan dapatkan lisensi.

Pemasangan

composer require nextpdf/pro:^3

Tinjauan konseptual

Alur kerja memiliki dua fase:

Pengumpulan. AutoTocCollector::extract($html, maxDepth) memindai HTML untuk tag <h1>–<h6> sampai batas kedalaman, men-strip markup dalam, men-decode entitas, menormalisasi spasi-putih, dan memancarkan value object TocHeading (level 0 = H1). Ia dapat menetapkan nomor halaman sekuensial atau menerapkan peta indeks-ke-halaman yang disediakan pemanggil.
Perenderan. AutoTocRenderer::render($headings, $config) menghasilkan satu string content-stream PDF per halaman TOC, dengan indentasi per level, dot leader opsional, dan nomor halaman opsional. Setiap baris yang terlihat dipancarkan sebagai operasi text-showing Tj sesuai ISO 32000-2:2020 §9.4.

AutoTocConfig adalah value object imutabel yang dikonfigurasi secara fluen yang mengendalikan judul, kedalaman, fon, spasi, margin, warna, ukuran halaman, dan apakah dot leader serta nomor halaman ditampilkan.

Mengapa dirancang seperti ini

Keputusan penopang utamanya adalah bahwa modul tidak pernah mengarang nomor halaman yang tidak dapat ia ketahui. Halaman target sebenarnya bergantung pada dokumen final yang sudah ditata, yang dimiliki pemanggil; sebuah tebakan akan melenceng secara diam-diam setiap kali paginasi berubah. Maka pengumpulan dan perenderan tetap terpisah dari tata letak. AutoTocCollector memancarkan heading dengan halaman null atau placeholder; nomor halaman sebenarnya tiba hanya melalui peta assignPageNumbers() yang disuplai pemanggil. Perenderan lalu menghasilkan operator content-stream biasa, menyerahkan penempatan halaman kepada pemanggil. Hasilnya tetap deterministik dan jujur: modul menyatakan apa yang tidak ia ketahui alih-alih mengarangnya.

Latar belakang desain: API yang menolak menebak.

Kontrak perilaku

Input. HTML (pengumpulan) dan sebuah daftar TocHeading (perenderan).
Output. list<TocHeading> dari pengumpulan; list<string> operator content-stream PDF (satu per halaman TOC) dari perenderan.
Nomor halaman. Entah ditetapkan secara sekuensial, disuplai melalui sebuah peta indeks-ke-halaman, atau dibiarkan null. Modul tidak menghitung halaman target sebenarnya dari dokumen yang sudah ditata; ia tidak menyelesaikan referensi-silang.
Kedalaman. maxDepth di-clamp ke 1–6. Heading yang lebih dalam dari kedalaman yang dikonfigurasi dilewati.
Determinisme. Untuk HTML dan konfigurasi yang identik, heading yang dikumpulkan dan operator yang dirender bersifat stabil.

Permukaan API publik

Tipe	Jenis	Anggota utama
`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`

Contoh kode — Mulai cepat

<?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";

Contoh kode — Produksi

<?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);
}

Kasus tepi & jebakan

Teks heading kosong (setelah strip tag) dilewati.
maxDepth di-clamp ke 1–6 baik di collector maupun config; nilai di-luar-rentang dikoreksi, bukan ditolak.
Nomor halaman adalah placeholder kecuali pemanggil menyuplai peta nyata; modul tidak menjalankan lintasan tata letak untuk menemukan halaman target sebenarnya.
Perender memancarkan operator content-stream untuk penempatan ke sebuah halaman; pemanggil bertanggung jawab menambahkan halaman-halaman tersebut ke dokumen.

Performa

Pengumpulan adalah satu lintasan ekspresi-reguler atas HTML. Perenderan bersifat linear terhadap jumlah heading, dipaginasi oleh entriesPerPage(). Lihat performance_budget.

Catatan keamanan

HTML dipindai dengan ekspresi reguler heading terbatas dan strip tag; tidak ada HTML yang dieksekusi dan tidak ada referensi eksternal yang diikuti. Teks yang dirender di-escape untuk sintaks string content-stream.

Kesesuaian

Klaim	Klausa spesifikasi	Status
Baris TOC dipancarkan sebagai operasi text-showing `Tj`	ISO 32000-2:2020 §9.4	Terverifikasi (rangkaian unit)
Resolusi referensi-silang dokumen langsung	—	Tidak didukung (nomor halaman disuplai pemanggil)

Fallback / alternatif Core

Tidak ada generator TOC Core. HTML sumber heading biasanya berasal dari pipeline HTML Core. Lihat /modules/core/html/.

Catatan batas Enterprise

Modul ini mengumpulkan heading dan merender operator TOC. Modul ini tidak melakukan resolusi referensi-silang lintas-dokumen, pembuatan indeks, atau sinkronisasi pohon-bookmark; urusan itu berada di luar cakupan.

Batas publikasi

Halaman ini hanya mendokumentasikan perilaku yang dapat diamati dari luar dan permukaan API publik yang didukung. Jalur namespace internal, kelas helper, tabel mekanisme, nama berkas runbook, dan prefiks tiket berada di luar cakupan.