Membagi HTML panjang ke beberapa halaman

Sekilas pandang

Gunakan pemenggalan halaman otomatis untuk mengalirkan konten panjang ke beberapa halaman. Tambahkan kerangka (outline) agar pembaca mudah berpindah antarbagian. Resep ini mengacu pada examples/12-bookmarks-and-toc.php.

Instalasi

composer require nextpdf/core:^3

Gunakan batasan versi ini untuk paket nextpdf/core. Contoh ini dapat berjalan pada PHP 8.4.

Gambaran konseptual

setAutoPageBreak(true, $margin) memberi tahu mesin untuk memulai halaman baru sebelum konten melewati ambang batas margin bawah. Mesin memenggal teks panjang yang ditulis melalui multiCell() atau writeHtml() pada batas tersebut. Modul Cascading Style Sheets (CSS) Fragmentation (css_break_3) memiliki peringkat Verified dalam matriks dukungan. Modul ini mendasari perilaku pemenggalan dalam alur Hypertext Markup Language (HTML).

bookmark($title, $level) menambahkan item kerangka untuk posisi saat ini. Item kerangka Portable Document Format (PDF) mengaitkan sebuah tujuan sehingga pembaca dapat langsung melompat ke suatu halaman (ISO 32000-2). Mesin menuliskan tujuan tersebut sebagai entri Dest pada item tersebut (ISO 32000-2). Gunakan argumen level untuk menyusun item secara bertingkat menjadi daftar isi hierarkis di bilah sisi pembaca.

Alur kerja tetap satu lintasan (single-pass) (ADR-001). Mesin menentukan pembagian halaman saat memancarkan aliran, tanpa mempertahankan pohon tata letak.

Permukaan API

setAutoPageBreak(bool $enabled, float $margin = 20): static — NextPDF\Core\Concerns\HasPages.
bookmark(string $title, int $level = 0, float $y = -1): static — NextPDF\Core\Concerns\HasNavigation.
multiCell(...) / writeHtml(string $html): static — NextPDF\Core\Concerns\HasTextOutput.

Tabel PHPDoc lengkap dibuat dari kode sumber.

Contoh kode — Mulai cepat

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setAutoPageBreak(true, margin: 25);
$doc->addPage();
$doc->bookmark('Section 1', level: 0);
$doc->setFont('helvetica', '', 11);

for ($i = 1; $i <= 80; $i++) {
    $doc->multiCell(0, 7, "Paragraph {$i} of a long flowing document.");
}

$doc->save(__DIR__ . '/out.pdf');

Contoh kode — Produksi

Contoh mandiri ini berjalan di dalam harness. Contoh ini membangun dokumen multibab dengan kerangka bertingkat dan pemenggalan halaman otomatis, serta selaras dengan examples/12-bookmarks-and-toc.php.

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setTitle('Bookmarks and Navigation');
$doc->setPrintHeader(false);
$doc->setPrintFooter(false);
$doc->setAutoPageBreak(true, margin: 25);

$chapters = [
    'Chapter 1: Introduction' => ['What is NextPDF?', 'Key Features'],
    'Chapter 2: Getting Started' => ['Installation', 'Your First PDF'],
    'Chapter 3: Advanced Topics' => ['Worker-safe Architecture', 'Streaming Output'],
];

$body = 'NextPDF is a modern PDF 2.0 library for PHP. This paragraph is '
    . 'repeated so the content overflows the page and the engine inserts '
    . 'an automatic page break at the bottom-margin threshold.';

foreach ($chapters as $chapter => $sections) {
    $doc->addPage();
    $doc->bookmark($chapter, level: 0);
    $doc->setFont('helvetica', 'B', 18);
    $doc->cell(0, 12, $chapter, newLine: true);
    $doc->ln(3);

    foreach ($sections as $section) {
        $doc->bookmark($section, level: 1);
        $doc->setFont('helvetica', 'B', 14);
        $doc->cell(0, 10, $section, newLine: true);
        $doc->setFont('helvetica', '', 11);
        for ($i = 0; $i < 12; $i++) {
            $doc->multiCell(0, 7, $body);
        }
        $doc->ln(4);
    }
}

$out = getenv('NEXTPDF_COOKBOOK_OUTPUT');
$doc->save($out !== false ? $out : __DIR__ . '/paginate-long-html.pdf');

echo "Wrote paginate-long-html.pdf\n";

Keluaran standar (STDOUT) yang diharapkan:

Wrote paginate-long-html.pdf

Kasus tepi & jebakan

Menonaktifkan lalu lupa. Saat pemenggalan halaman otomatis dinonaktifkan, mesin memotong konten yang melewati margin bawah alih-alih mengalirkannya. Aktifkan kembali sebelum konten panjang.
Konten yang tidak dapat dipenggal. Sebuah blok tunggal yang lebih tinggi daripada tinggi halaman yang dapat digunakan bisa memunculkan UnsplittableContentException. Baris tabel yang sangat tinggi atau gambar berukuran besar dapat menyebabkan hal ini. Pisahkan konten sumbernya.
Penanda sebelum konten. Panggil bookmark() pada posisi tujuan yang Anda inginkan. Tempatkan tepat sebelum judul berikutnya, pada halaman yang Anda inginkan.
Header dan footer halaman menyisakan ruang. Header atau footer yang dicetak mengurangi tinggi konten yang dapat digunakan, dan ambang batas pemenggalan memperhitungkannya. Menonaktifkan keduanya, seperti yang dilakukan contoh ini, memberi Anda tinggi area halaman secara penuh.
Hierarki kerangka. level adalah kedalaman hierarki. Item anak pada level: 1 harus mengikuti induk level: 0. Jika tidak, pembaca akan meratakan pohon kerangka.

Performa

Mesin menentukan pembagian halaman dalam satu lintasan saat memancarkan output. Biayanya linear terhadap panjang konten, O(n). Anggarannya adalah wall_ms: 2000, peak_mb: 96. Wall time sedikit lebih tinggi daripada resep satu halaman karena referensi silang (xref) multihalaman dan penyusunan kerangka menambah beban kerja. Model streaming menjaga penggunaan memori tetap terbatas, dan kerangka tetap berupa daftar datar yang kecil.

Kutipan matriks dukungan CSS (hanya baris Verified)

Tabel ini hanya menampilkan kembali baris Verified dari matriks dukungan CSS yang telah diaudit kebenarannya.

Modul W3C	Level	Status	Bukti
CSS Fragmentation (`css_break_3`)	3	Verified	`src/Html/Fragmentation/`, `tests/Unit/Html/PagedMedia/`
CSS Table (`css_tables_3`)	3	Verified	`src/Html/Table/` + PDF golden
CSS Cascading and Inheritance (`css_cascade_3`)	3	Verified	`src/Html/Cascade/`

Selektor halaman bernama @page termasuk dalam CSS Paged Media. Sebelum Anda mengandalkannya, periksa matriks untuk peringkat modul tersebut saat ini.

Batasan streaming satu lintasan (ADR-001)

Mesin memancarkan pemenggalan halaman seiring aliran konten berjalan. Karena tidak ada pohon yang dipertahankan untuk dialirkan ulang, setiap keputusan pemenggalan bersifat final. Sebagian konten, seperti referensi silang, memerlukan nomor halaman final setelah tata letak. Konten tersebut memiliki keterbatasan, jadi tulislah dengan mempertimbangkan batasan itu.

Kontrak lapisan (ADR-010)

Pembagian halaman menjadi tanggung jawab pengendali pemenggalan halaman, bukan pengurai. Pengurai tidak memancarkan operator transisi halaman mentah; ia meminta pemenggalan melalui kontrak pengendali.

Anggaran memori untuk dokumen besar

Model streaming menyimpan buffer halaman saat ini dan daftar kerangka datar, bukan semua halaman sekaligus. Dokumen yang sangat panjang tetap berada dalam batas atas ADR-020 karena mesin membuang (flush) halaman yang telah selesai. Tabel dan kontainer flex tetap mematuhi batas 5,000 node per konteks.

Catatan keamanan

Dokumen berbahaya tidak dapat memaksa penggunaan memori tanpa batas. Batas atas elemen dan hierarki (ADR-001), ditambah anggaran node per konteks (ADR-020), membatasi beban kerja. Validasi panjang dan struktur konten panjang yang disediakan pengguna. Mesin merender judul kerangka yang dikendalikan penyerang sebagai teks dan tidak pernah menafsirkannya.

Kesesuaian

Pernyataan	Spesifikasi	Klausa	reference_id
Setiap item kerangka dapat dikaitkan dengan sebuah tujuan sehingga pengguna dapat langsung melompat ke item tersebut.	ISO 32000-2	iso32000_2_sec12#x1.x5.p4
Entri Dest dari item kerangka menamai tujuan yang ditampilkan saat item tersebut diaktifkan.	ISO 32000-2	iso32000_2_sec12#x1.x11.p30

Resep ini menunjukkan cara NextPDF mengalirkan konten panjang dan membangun kerangka. Matriks dukungan memberi CSS Fragmentation peringkat Verified.

Konteks komersial

Tidak berlaku.