Otomatik sayfa sonlarıyla çok sayfalı belge oluşturma

Bir bakışta

Çok sayfaya yayılan bir belge oluşturun. İçeriği adım adım ekleyin. setAutoPageBreak() etkinleştirildiğinde, imleç alt kenar boşluğuna ulaştığında yerleşim motoru yeni bir sayfa başlatır. save() çağrısından sonra, nihai sayfa sayısını getNumPages() ile okuyun. Bu tarif examples/05-multi-page.php dosyasını izler.

Motor, save() çağrısı sırasında her sayfanın işaretlemelerini bir içerik akışına yazar. ISO 32000-2 §7.7.3.3, bir sayfanın Contents öğesini tek bir akış olarak ya da sırayla birleştirilmiş bir akış dizisi olarak tanımlar. Bu nedenle çok sayfalı çıktı, tek bir arabellek değil, sayfa nesnelerinden oluşan bir dizidir.

Kurulum

composer require nextpdf/core:^3

Herhangi bir isteğe bağlı uzantı gerekmez. Bu tarif, PHP 8.1–8.4 geri uyarlama matrisinde çalışır. getNumPages() ve setAutoPageBreak() yöntemlerinin her ikisi de 1.0.0 sürümünden bu yana kararlıdır.

Kavramsal genel bakış

Bir NextPDF belgesi bir sayfa ağacıdır. İçerik ekledikçe, iç imleç (getY()) sayfada aşağı doğru ilerler. Otomatik sayfa sonları açık olduğunda, motor her içerik bloğundan önce kalan dikey alanı denetler. Blok alt kenar boşluğunun üstüne sığmayacaksa, motor geçerli sayfayı boşaltır ve sizin yerinize addPage() çağrısını yapar. setAutoPageBreak() yöntemine ilettiğiniz alt kenar boşluğu tetikleme eşiğidir.

Ortam kutusu gibi sayfa düzeyindeki öznitelikler kalıtılabilir. ISO 32000-2 §7.7.3.4, bir sayfa nesnesinde bulunmayan bir özniteliğin üstteki bir sayfa ağacı düğümünden çözümlendiğini belirtir. NextPDF, belge boyunca tutarlı tek bir sayfa boyutu ayarlar; böylece oluşturulan her sayfa aynı geometriyi kullanır ve bunu her sayfa için yinelemeniz gerekmez.

API yüzeyi

Uygulama programlama arabirimi (API) yüzeyi PHPDoc’tan oluşturulur. Bu tarif şu yöntemlere dayanır:

Document::createStandalone(): self — yalıtılmış bir belge oluşturur.
setAutoPageBreak(bool $enabled, float $margin = 20): static — otomatik sayfa sonlarını etkinleştirir. $margin, alt kenar boşluğu tetikleyicisini milimetre cinsinden belirtir.
addPage(?PageSize $size = null, Orientation $orientation = Orientation::Portrait): static — ilk sayfayı ve açıkça belirtilen her sayfayı başlatır.
multiCell(...): static / cell(...): static — akan veya sabit metin blokları yazar. Sayfa sonu denetimi bu blokları ölçer.
getNumPages(): int — yerleşimden sonraki sayfa sayısı.

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->setFont('helvetica', '', 11);
for ($i = 1; $i <= 60; $i++) {
    $doc->multiCell(0, 7, "Line {$i}: content flows until the page is full, "
        . 'then the engine starts a new page automatically.');
}

$doc->save(getenv('NEXTPDF_COOKBOOK_OUTPUT') ?: __DIR__ . '/multi-page.pdf');
echo 'Pages: ' . $doc->getNumPages() . "\n";

Kod örneği — üretim

Bu, eksiksiz ve koşum altyapısına hazır bir örnektir. Koşum altyapısının ayarladığı NEXTPDF_COOKBOOK_OUTPUT değişkenine uyar; bu nedenle PDF’yi STDOUT’a yazdırmayın. Kendi entropisini eklemez. Koşum altyapısı bunu çalıştırdığında, DeterministicMode saati, /ID öğesini ve markalamayı sabitler.

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setTitle('Multi-Page Document');

// Enable automatic page breaks. The 25 mm bottom margin is the trigger:
// when the cursor would cross it, the engine flushes the page and adds
// a new one before the next block is drawn.
$doc->setAutoPageBreak(true, margin: 25);
$doc->addPage();

$doc->setFont('helvetica', 'B', 18);
$doc->cell(0, 12, 'Multi-Page Document Example', newLine: true);
$doc->ln(5);

for ($chapter = 1; $chapter <= 3; $chapter++) {
    $doc->setFont('helvetica', 'B', 14);
    $doc->cell(0, 10, "Chapter {$chapter}: Lorem Ipsum", newLine: true);
    $doc->setFont('helvetica', '', 11);

    for ($para = 1; $para <= 5; $para++) {
        $text = "Paragraph {$para} of Chapter {$chapter}. "
            . 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. '
            . 'Sed do eiusmod tempor incididunt ut labore et dolore magna '
            . 'aliqua. Ut enim ad minim veniam, quis nostrud exercitation '
            . 'ullamco laboris nisi ut aliquip ex ea commodo consequat.';
        $doc->multiCell(0, 7, $text);
        $doc->ln(3);
    }
    $doc->ln(5);
}

// The harness sets NEXTPDF_COOKBOOK_OUTPUT; honour it. STDOUT stays free
// for progress text only.
$out = getenv('NEXTPDF_COOKBOOK_OUTPUT') ?: __DIR__ . '/multi-page.pdf';
$doc->save($out);

echo 'Created multi-page.pdf with ' . $doc->getNumPages() . " pages\n";

Sınır durumları ve tuzaklar

Otomatik sayfa sonu devre dışı. setAutoPageBreak(false, …) ile alt kenar boşluğunu aşan içerik akıtılmaz, sayfada kırpılır ve belge tek bir sayfada kalır. Akan içerik için bunu etkinleştirin.
Sayfadan daha uzun tek bir blok. Motor, metni yazdırılabilir yüksekliği aşan bir multiCell öğesini dahili olarak böler. Ancak uzun bir görüntü gibi kullanılabilir alandan daha uzun, bölünemeyen tek bir blok yalnızca bir kez yerleştirilir ve taşar. Bunu kendiniz bölün.
İlk addPage() çağrısı yine de gereklidir. Hiçbir sayfa yokken cell(), gerektiğinde addPage() çağrısını yapar. Yine de ilk sayfanın boyutu ve yönü belirlenimci kalsın diye addPage() çağrısını açıkça yapın.
Kenar boşluğu birimleri. setAutoPageBreak() kenar boşluğu, varsayılan birim sisteminde nokta cinsinden değil, milimetre cinsindendir.

Başarım

getNumPages() O(1) karmaşıklığındadır. Bir sayaç okur ve yerleşimi yeniden çalıştırmaz. Bellek, sayfa sayısıyla değil, tutulan içerikle ölçeklenir. Motor, tamamlanan sayfaları tamamlandıkça çıkış arabelleğine boşaltır — tek geçişli akış modeli (ADR-001). 2000 ms / 64 MB bütçesi, referans ana makinede birkaç yüz sayfalık metin belgelerini kapsar.

Güvenlik notları

Bu tarif yalnızca kodunuzun sağladığı metni yazar. Hiçbir girdi ayrıştırması, ağ erişimi veya seri durumdan çıkarma işlemi gerçekleştirmez. Dış kaynaklı her metni güvenilmez kabul edin ve işlemeden önce bir uzunluk sınırı uygulayın. Motor, sizin yerinize uygulama düzeyinde bir içerik boyutu sınırı dayatmaz.

Uygunluk

İfade	Belirtim	Madde
Bir sayfanın `Contents` öğesi tek bir akıştır ya da sıralı, birleştirilmiş bir akış dizisidir.	ISO 32000-2	§7.7.3.3
Bir sayfa nesnesinde bulunmayan, kalıtılabilir bir sayfa özniteliği üstteki bir sayfa ağacı düğümünden çözümlenir.	ISO 32000-2	§7.7.3.4
Fragman `/ID` öğesi, iki bayt dizesinden oluşan bir dosya tanımlayıcısıdır (PDF 2.0’da gereklidir).	ISO 32000-2	§7.5.5

Yeniden üretilebilirlik profili — yapısal (neden bit düzeyinde değil). Kaydedilen her belge, iki bayt dizesi bir dosya tanımlayıcısı olan bir fragman /ID öğesi taşır (yukarıda, ISO 32000-2 §7.5.5). İkinci öğe çalıştırmalar arasında kararlı değildir; bu nedenle özdeş içerik için bile ham baytlar çalıştırmalar arasında farklılık gösterir. Koşum altyapısı, /ID, /CreationDate ve /ModDate öğelerini çıkaran qpdf ile normalleştirilmiş yapıyı karşılaştırır. Bu tarif, NextPDF uygulamasının yapıyı nasıl ürettiğini açıklar. Genel bir iddia olarak ISO 32000-2 uygunluğunu öne sürmez.

Ticari bağlam

Geçerli değildir. Otomatik sayfa sonlarıyla çok sayfalı oluşturma, Premium engeli olmayan bir Core yeteneğidir.