PageBackfill: buffer halaman dipertahankan

Sekilas

Preview opt-in. Buffer halaman dipertahankan default-mati. Dengan ia mati, writer adalah serializer streaming sebagaimana selama ini — byte-identik. Aktifkan hanya saat Anda benar-benar perlu menggambar pada halaman terdahulu, dan baca daftar fail-closed di bawah ini terlebih dahulu.

Secara default, writer melakukan streaming halaman dan mem-flush-nya secara berurutan; begitu sebuah halaman di-flush, ia tidak dapat digambari lagi. Buffer halaman dipertahankan adalah opt-in yang menahan halaman yang sudah di-flush sehingga sebuah halaman yang sudah di-flush dapat diisi-ulang — digambari pada halaman terdahulu — sebelum dokumen diserialisasi. Penggunaan klasiknya adalah total atau kotak ringkasan yang baru dapat Anda tempatkan setelah halaman berikutnya ditata.

Pemasangan

composer require nextpdf/core:^3

Buffer halaman dipertahankan disertakan dalam paket core. Config::withRetainedPageBuffer() dan metode pengisian-ulang Document adalah @since 6.1.0. Default tetap writer streaming. ADR-037, yang sebelumnya menangguhkan kapabilitas ini, kini tercatat sebagai terimplementasi.

Ikhtisar konseptual

Config::withRetainedPageBuffer() memilihkan sebuah dokumen ke halaman dipertahankan. Begitu aktif, Document::setActiveBackfillPage(int $pageIndex) mengalihkan penggambaran ke halaman terdahulu yang sudah di-flush; Document::endPageBackfill() mengembalikan penggambaran ke posisi append normal. Konten yang Anda tulis di antara kedua panggilan itu mendarat pada halaman terdahulu. Buffer menahan halaman hingga save(), sehingga pengisian-ulang diterapkan sebelum tabel referensi-silang dan trailer ditulis (ISO 32000-2 §7.5).

Batasan fail-closed — kombinasi yang ditolak

Pengisian-ulang adalah operasi akses-acak, dan beberapa fitur dokumen mengasumsikan byte append-only yang di-streaming. Buffer halaman dipertahankan menolak digabung dengan salah satunya, terlepas dari urutan dan sebelum serialisasi, sehingga ia tidak pernah dapat diam-diam merusak tanda tangan atau klaim konformitas:

• Sebuah tanda tangan digital.
• PDF bertag (pohon struktur).
• PDF/A.
• Linearisasi.
• Pengemasan object stream.
• Enkripsi.
• Mode rendering Safe CSS.

Anggaran byte-tak-terkompresi per-dokumen membatasi seberapa banyak yang boleh ditahan buffer; dokumen yang melampauinya gagal-keras alih-alih mengonsumsi memori tak-terbatas. Default streaming masih gagal secara fail-closed begitu pemanggil mencoba peralihan akses-acak tanpa opt-in — mengaktifkan buffer adalah satu-satunya cara mendapatkan pengisian-ulang, dan ia tidak kompatibel dengan fitur-fitur di atas secara konstruksi.

Permukaan API

Simbol	Lokasi	Peran
Config::withRetainedPageBuffer(bool $enabled = true): self	src/Core/Config.php	Memilihkan sebuah dokumen ke buffer halaman dipertahankan.
Document::setActiveBackfillPage(int $pageIndex): static	src/Core/Document.php	Mengalihkan penggambaran ke halaman terdahulu yang sudah di-flush.
Document::endPageBackfill(): static	src/Core/Document.php	Mengembalikan penggambaran ke posisi append normal.

Sebuah percobaan pengisian-ulang yang melanggar kombinasi yang ditolak memunculkan eksepsi konfigurasi bertipe pada batasnya, bukan dokumen yang rusak.

Contoh kode — Mulai cepat

Cadangkan satu tempat pada halaman satu, isi sisa dokumen, lalu isi-ulang tempat yang dicadangkan dengan nilai yang dihitung di akhir.

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

Contoh kode — Produksi

Jaga buffer tetap mati untuk dokumen apa pun yang ditandatangani, bertag, PDF/A, ter-linearisasi, terenkripsi, atau object stream — itulah persis kombinasi yang ditolak buffer. Pilih satu jalur secara eksplisit.

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

Kasus tepi & jebakan

• Mati bersifat byte-identik. Dengan buffer mati, writer melakukan streaming seperti sebelumnya.
• Saling eksklusif dengan penandatanganan, tagging, PDF/A, linearisasi, object stream, enkripsi, dan mode Safe CSS. Penolakan ini terlepas dari urutan dan terpicu sebelum serialisasi. Rencanakan dokumen untuk satu mode atau yang lain.
• Anggaran byte gagal-keras. Buffer dipertahankan bersifat terbatas; dokumen yang melampaui anggaran byte-tak-terkompresi gagal alih-alih tumbuh tanpa batas.
• Pasangkan panggilannya. Setiap setActiveBackfillPage() harus dipadankan dengan endPageBackfill() agar konten berikutnya di-append secara normal.
• Default streaming menolak akses acak. Tanpa opt-in, peralihan akses-acak gagal secara fail-closed. Buffer adalah satu-satunya jalur yang didukung.

Kinerja

Buffer halaman dipertahankan menukar memori dengan kapabilitas pengisian-ulang: ia menahan halaman yang sudah di-flush hingga save(), dibatasi oleh anggaran byte-tak-terkompresi per-dokumen. Profil memori datar writer streaming hanya berlaku saat buffer mati. performance_budget (wall_ms: 1500, peak_mb: 128) mencerminkan langit-langit memori yang lebih tinggi pada jalur dipertahankan.

Catatan keamanan

Buffer halaman dipertahankan tidak memperlebar permukaan masukan; ia mengubah kapan byte diserialisasi, bukan apa yang diingesti. Penolakannya untuk digabung dengan enkripsi dan penandatanganan adalah properti keselamatan: sebuah pengisian-ulang tidak akan pernah dapat mengubah byte yang ditandatangani atau terenkripsi setelah faktanya, karena keduanya tidak dapat diaktifkan bersama. Anggaran byte membatasi memori terhadap dokumen yang hostil.

Konformitas

Pernyataan	Standar	Klausul
Writer menserialisasi body, struktur referensi-silang, dan trailer pada waktu save.	ISO 32000-2	§7.5

Ini adalah kapabilitas preview. NextPDF menolak buffer pengisian-ulang untuk dokumen yang ditandatangani, bertag, PDF/A, ter-linearisasi, terenkripsi, dan object stream, sehingga ia tidak membuat klaim konformitas untuk profil-profil itu melalui jalur ini. Tidak ada teks standar yang direproduksi.

Adapter Compat (TCPDF)

Adapter kompatibilitas TCPDF mengekspos kapabilitas ini sebagai ekstensi konstruktor. Konstruksikan adapter dengan retainedPageBuffer: true, lalu sebuah panggilan setPage() atau lastPage() yang menargetkan halaman terdahulu mendelegasikan ke pengisian-ulang core alih-alih memunculkan UnsupportedFeatureException streaming. Argumen konstruktor ini adalah ekstensi NextPDF, bukan paritas TCPDF legacy — TCPDF legacy tidak memiliki flag semacam itu. Penolakan fail-closed yang sama berlaku. Lihat halaman retained-page-buffer adapter compat untuk detail sisi-adapter.

Lihat juga

• Modul Writer
• Modul Document
• Modul Config
• Modul linearisasi