PageBackfill: korunan sayfa arabelleği

Bir bakışta

Katılımlı önizleme. Korunan sayfa arabelleği varsayılan olarak kapalıdır. Kapalıyken yazıcı, her zaman olduğu gibi akış serileştiricisidir — bayt düzeyinde özdeş. Bunu yalnızca gerçekten daha önceki bir sayfaya çizmeniz gerektiğinde açın ve önce aşağıdaki hata-durumunda-kapalı listesini okuyun.

Yazıcı varsayılan olarak sayfaları akıtır ve sırayla boşaltır; bir sayfa boşaltıldıktan sonra üzerine yeniden çizilemez. Korunan sayfa arabelleği, boşaltılan sayfaları tutan katılımlı seçenektir; böylece daha önce boşaltılmış bir sayfa, belge serileştirilmeden önce geri doldurulabilir — daha önceki bir sayfanın üzerine çizilebilir. Klasik kullanım, yalnızca sonraki sayfalar yerleştirildikten sonra yerleştirebileceğiniz bir genel toplam ya da özet kutusudur.

Kurulum

composer require nextpdf/core:^3

Korunan sayfa arabelleği core paketiyle birlikte gelir. Config::withRetainedPageBuffer() ve Document geri doldurma yöntemleri @since 6.1.0 şeklindedir. Varsayılan, akış yazıcısı olarak kalır. Daha önce bu yeteneği erteleyen ADR-037 artık uygulanmış olarak kayda geçirilmiştir.

Kavramsal genel bakış

Config::withRetainedPageBuffer(), bir belgeyi korunan sayfalara dahil eder. Açıldıktan sonra Document::setActiveBackfillPage(int $pageIndex) çizimi daha önceki, zaten boşaltılmış bir sayfaya yönlendirir; Document::endPageBackfill() çizimi normal ekleme konumuna döndürür. İki çağrı arasında yazdığınız içerik daha önceki sayfaya iner. Arabellek, sayfaları save() çağrısına kadar tutar; böylece geri doldurma, çapraz başvuru tablosu ve fragman yazılmadan önce uygulanır (ISO 32000-2 §7.5).

Hata-durumunda-kapalı sınırı — reddedilen birleşimler

Geri doldurma rastgele erişimli bir işlemdir ve birkaç belge özelliği yalnızca ekleme, akıtılan baytlar varsayar. Korunan sayfa arabelleği, sıradan bağımsız olarak ve serileştirmeden önce bunların hiçbiriyle birleşmeyi reddeder; böylece bir imzayı ya da bir uygunluk iddiasını asla sessizce bozamaz:

• Bir dijital imza.
• Etiketli PDF (yapı ağacı).
• PDF/A.
• Doğrusallaştırma.
• Nesne-akışı paketleme.
• Şifreleme.
• Safe CSS işleme kipi.

Belge başına sıkıştırılmamış-bayt bütçesi, arabelleğin ne kadar tutabileceğini üst sınıra bağlar; bunu aşan bir belge, sınırsız bellek tüketmek yerine katı biçimde başarısız olur. Akış varsayılanı, bir çağıran katılım olmadan rastgele erişimli bir geçiş denediği an hâlâ hata durumunda kapalı kalır — arabelleği açmak, geri doldurma elde etmenin tek yoludur ve yapısı gereği yukarıdaki özelliklerle uyumsuzdur.

API yüzeyi

Simge	Konum	Rol
Config::withRetainedPageBuffer(bool $enabled = true): self	src/Core/Config.php	Bir belgeyi korunan sayfa arabelleğine dahil eder.
Document::setActiveBackfillPage(int $pageIndex): static	src/Core/Document.php	Çizimi daha önceki, zaten boşaltılmış bir sayfaya yönlendirir.
Document::endPageBackfill(): static	src/Core/Document.php	Çizimi normal ekleme konumuna döndürür.

Reddedilen bir birleşimi ihlal eden bir geri doldurma girişimi, bozuk bir belge değil, sınırda türlenmiş bir yapılandırma istisnası yükseltir.

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

Birinci sayfada bir nokta ayırın, belgenin geri kalanını doldurun, ardından ayrılan noktayı sonda hesaplanan bir değerle geri doldurun.

<?php

declare(strict_types=1);

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

use NextPDF\Core\Config;
use NextPDF\Core\Document;

$config = (new Config())->withRetainedPageBuffer();

$doc = Document::createStandalone($config);
$doc->addPage();                 // page 0 — leaves room for a grand total
$doc->writeHtml('<h1>Invoice</h1>');

$doc->addPage();                 // page 1 — line items
$doc->writeHtml('<p>Line items…</p>');
$total = 1234.56;                // computed after laying out the items

$doc->setActiveBackfillPage(0);  // draw back onto page 0
$doc->writeHtml('<p>Grand total: ' . number_format($total, 2) . '</p>');
$doc->endPageBackfill();

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

Kod örneği — üretim

İmzalı, etiketli, PDF/A, doğrusallaştırılmış, şifreli ya da nesne-akışlı herhangi bir belge için arabelleği kapalı tutun — bunlar tam olarak arabelleğin reddettiği birleşimlerdir. Bir yolu açıkça seçin.

<?php

declare(strict_types=1);

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

use NextPDF\Core\Config;
use NextPDF\Core\Document;

function renderReport(bool $needsBackfill, bool $mustBeSigned): Document
{
    if ($needsBackfill && $mustBeSigned) {
        // The buffer refuses to combine with signing. Resolve the requirement
        // before building: pre-compute the value, or sign a separate pass.
        throw new \LogicException('Back-fill and signing are mutually exclusive.');
    }

    $config = new Config();
    if ($needsBackfill) {
        $config = $config->withRetainedPageBuffer();
    }

    return Document::createStandalone($config);
}

Sınır durumları ve dikkat edilmesi gerekenler

• Kapalı bayt düzeyinde özdeştir. Arabellek kapalıyken yazıcı önceki gibi akıtır.
• İmzalama, etiketleme, PDF/A, doğrusallaştırma, nesne akışları, şifreleme ve Safe CSS kipiyle karşılıklı olarak dışlayıcıdır. Reddetme sıradan bağımsızdır ve serileştirmeden önce tetiklenir. Belgeyi şu ya da bu kip için planlayın.
• Bayt bütçesi katı biçimde başarısız olur. Korunan arabellek sınırlıdır; sıkıştırılmamış-bayt bütçesini aşan bir belge, sınırsız büyümek yerine başarısız olur.
• Çağrıları eşleştirin. Her setActiveBackfillPage(), sonraki içeriğin normal biçimde eklenmesi için bir endPageBackfill() ile eşleştirilmelidir.
• Akış varsayılanı rastgele erişimi reddeder. Katılım olmadan rastgele erişimli bir geçiş hata durumunda kapalı kalır. Arabellek, desteklenen tek yoldur.

Performans

Korunan sayfa arabelleği, geri doldurma yeteneği karşılığında bellekten ödün verir: boşaltılan sayfaları, belge başına sıkıştırılmamış-bayt bütçesiyle sınırlanmış biçimde save() çağrısına kadar tutar. Akış yazıcısının düz bellek profili yalnızca arabellek kapalıyken geçerlidir. performance_budget (wall_ms: 1500, peak_mb: 128), korunan yolun daha yüksek bellek tavanını yansıtır.

Güvenlik notları

Korunan sayfa arabelleği giriş yüzeyini genişletmez; alınanı değil, baytların ne zaman serileştirildiğini değiştirir. Şifreleme ve imzalamayla birleşmeyi reddetmesi bir güvenlik özelliğidir: bir geri doldurma, imzalı ya da şifreli baytları sonradan asla değiştiremez; çünkü ikisi birlikte etkinleştirilemez. Bayt bütçesi, düşmanca bir belgeye karşı belleği sınırlar.

Uygunluk

İfade	Standart	Madde
Yazıcı, kaydetme sırasında gövdeyi, çapraz başvuru yapısını ve fragmanı serileştirir.	ISO 32000-2	§7.5

Bu bir önizleme yeteneğidir. NextPDF, imzalı, etiketli, PDF/A, doğrusallaştırılmış, şifreli ve nesne-akışlı belgeler için geri doldurma arabelleğini reddeder; bu nedenle bu yoldan o profiller için hiçbir uygunluk iddiasında bulunmaz. Hiçbir standart metin olduğu gibi aktarılmaz.

Compat (TCPDF) adaptörü

TCPDF uyumluluk adaptörü, bu yeteneği bir yapıcı uzantısı olarak açığa çıkarır. Adaptörü retainedPageBuffer: true ile oluşturun; o zaman daha önceki bir sayfayı hedefleyen bir setPage() ya da lastPage() çağrısı, akış UnsupportedFeatureException istisnasını yükseltmek yerine çekirdek geri doldurmaya yetki devreder. Bu yapıcı argümanı bir NextPDF uzantısıdır, eski TCPDF eşliği değil — eski TCPDF’te böyle bir bayrak yoktur. Aynı hata-durumunda-kapalı reddetmeleri geçerlidir. Adaptör tarafındaki ayrıntılar için compat adaptörünün korunan-sayfa-arabelleği sayfasına bakın.

Ayrıca bakınız

• Writer modülü
• Document modülü
• Config modülü
• Linearization modülü