Uzun HTML içeriğini sayfalara bölün

Bir bakışta

Uzun içeriği sayfalara akıtmak için otomatik sayfa sonlarını kullanın. Okuyucuların bölümler arasında gezinebilmesi için bir ana hat ekleyin. Bu tarif, examples/12-bookmarks-and-toc.php dosyasını temel alır.

Kurulum

composer require nextpdf/core:^3

Bu sürüm kısıtını nextpdf/core paketi için kullanın. Örnek, PHP 8.4 üzerinde çalışır.

Kavramsal genel bakış

setAutoPageBreak(true, $margin), içerik alt kenar boşluğu eşiğini aşmadan önce motora yeni bir sayfa başlatmasını bildirir. Motor, multiCell() veya writeHtml() aracılığıyla yazılan uzun metni bu sınırda parçalara ayırır. CSS Fragmentation modülü (css_break_3) destek matrisinde Doğrulanmış olarak derecelendirilir. HTML ardışık düzeninde sonlandırma davranışını destekler.

bookmark($title, $level), geçerli konum için bir ana hat öğesi ekler. Bir PDF ana hat öğesi, okuyucuların doğrudan bir sayfaya geçebilmesi için bir hedefle ilişkilendirilir (ISO 32000-2). Motor, bu hedefi öğenin Dest girdisi olarak yazar (ISO 32000-2). Öğeleri okuyucunun kenar çubuğunda hiyerarşik bir içindekiler tablosuna yuvalamak için level bağımsız değişkenini kullanın.

Ardışık düzen tek geçişli kalır (ADR-001). Motor, saklanan bir yerleşim ağacı olmadan, akışı üretirken sayfalandırma kararını verir.

API yüzeyi

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.

Tam PHPDoc tablosu kaynak koddan oluşturulur.

Kod örneği — hızlı başlangıç

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

Kod örneği — üretim

Bu bağımsız örnek, test düzeneğinde çalışır. Yuvalanmış bir ana hat ve otomatik sayfa sonlarıyla çok bölümlü bir belge oluşturur; examples/12-bookmarks-and-toc.php dosyasını yansıtır.

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

Beklenen standart çıktı (STDOUT):

Wrote paginate-long-html.pdf

Uç durumlar ve püf noktaları

Devre dışı bırakıp unutmak. Otomatik sayfa sonu devre dışı bırakıldığında motor, içeriği akıtmak yerine alt kenar boşluğunu aşan kısmı kırpar. Uzun içerikten önce yeniden etkinleştirin.
Bölünemeyen içerik. Kullanılabilir sayfa yüksekliğinden daha yüksek tek bir blok UnsplittableContentException oluşturabilir. Buna çok yüksek bir tablo satırı veya büyük bir görüntü yol açabilir. Kaynak içeriği bölün.
İçerikten önce yer imi. bookmark() işlevini, hedefin işaret etmesini istediğiniz konumda çağırın. İstediğiniz sayfada, bir sonraki başlığın hemen önüne yerleştirin.
Üst bilgi ve alt bilgi alan ayırır. Bir yazdırma üst bilgisi veya alt bilgisi kullanılabilir içerik yüksekliğini azaltır ve sonlandırma eşiği bunu hesaba katar. Bu örnekte olduğu gibi her ikisini de devre dışı bırakmak, gövde için tüm yüksekliği kullanılabilir kılar.
Ana hat yuvalaması. level yuvalama derinliğidir. level: 1 konumundaki bir alt öğe, bir level: 0 üst öğesini izlemelidir. Aksi takdirde okuyucu, ana hat ağacını düzleştirir.

Performans

Motor, sayfalandırma kararlarını tek bir yayma geçişi sırasında verir. Maliyet, içerik uzunluğuyla doğrusaldır, O(n). Bütçe wall_ms: 2000, peak_mb: 96 şeklindedir. Çok sayfalı çapraz başvuru (xref) ve ana hat birleştirme ek iş getirdiğinden, geçen gerçek süre tek sayfalı tariflerden biraz daha yüksek olabilir. Akış modeli belleği sınırlı tutar ve ana hat küçük, düz bir liste olarak kalır.

CSS destek matrisi alıntısı (yalnızca Doğrulanmış satırlar)

Bu tablo, yalnızca Doğrulanmış satırları, doğruluğu denetlenmiş CSS destek matrisinden yeniden verir.

W3C modülü	Düzey	Durum	Kanıt
CSS Fragmentation (`css_break_3`)	3	Doğrulanmış	`src/Html/Fragmentation/`, `tests/Unit/Html/PagedMedia/`
CSS Table (`css_tables_3`)	3	Doğrulanmış	`src/Html/Table/` + altın PDF’ler
CSS Cascading and Inheritance (`css_cascade_3`)	3	Doğrulanmış	`src/Html/Cascade/`

@page adlandırılmış sayfa seçicileri CSS Paged Media kapsamına aittir. Bunlara dayanmadan önce, o modülün geçerli derecesi için matrise başvurun.

Tek geçişli akış kısıtlamaları (ADR-001)

Motor, akış ilerledikçe sayfa sonlarını üretir. Yeniden akıtılacak saklanan bir ağaç bulunmadığından, her sonlandırma kararı kesindir. Çapraz başvuru gibi bazı içerikler, son sayfa numarasına yerleşimden sonra ihtiyaç duyar. Bu tür içerik kısıtlıdır; bu nedenle onu bu sınırı göz önünde bulundurarak yazın.

Katman sözleşmeleri (ADR-010)

Sayfalandırma, ayrıştırıcıya değil sayfa sonu denetleyicisine aittir. Ayrıştırıcı, ham sayfa geçiş işleçleri üretmez; denetleyici sözleşmesi aracılığıyla bir sonlandırma talep eder.

Büyük belgeler için bellek bütçesi

Akış modeli, tüm sayfaları aynı anda değil, geçerli sayfa arabelleğini ve düz ana hat listesini tutar. Motor tamamlanan sayfaları boşalttığından, çok uzun bir belge ADR-020 üst sınırı içinde kalır. Tablolar ve esnek kapsayıcılar yine de bağlam başına 5,000 düğüm sınırına tabidir.

Güvenlik notları

Kötü amaçlı bir belge, sınırsız bellek kullanımını zorlayamaz. Öğe ve yuvalama üst sınırları (ADR-001) ile bağlam başına düğüm bütçesi (ADR-020), işi sınırlar. Kullanıcı tarafından sağlanan uzun içeriğin uzunluğunu ve yapısını doğrulayın. Motor, saldırgan denetimindeki bir ana hat başlığını metin olarak işler ve onu asla yorumlamaz.

Uyumluluk

İfade	Spesifikasyon	Madde	reference_id
Her ana hat öğesi, kullanıcının doğrudan ona geçebilmesi için bir hedefle ilişkilendirilebilir.	ISO 32000-2	iso32000_2_sec12#x1.x5.p4
Bir ana hat öğesinin Dest girdisi, öğe etkinleştirildiğinde görüntülenen hedefi adlandırır.	ISO 32000-2	iso32000_2_sec12#x1.x11.p30

Bu tarif, NextPDF’in uzun içeriği nasıl akıttığını ve bir ana hat oluşturduğunu gösterir. Destek matrisi, CSS Fragmentation modülünü Doğrulanmış olarak derecelendirir.

Ticari bağlam

Uygulanamaz.