PageBackfill: buffer di pagina mantenuto

In sintesi

Anteprima opt-in. Il buffer di pagina mantenuto è disattivato per impostazione predefinita. Con esso spento, il writer è il serializzatore in streaming che è sempre stato — byte-identico. Attivalo solo quando hai realmente bisogno di disegnare su una pagina precedente e leggi prima l’elenco fail-closed qui sotto.

Per impostazione predefinita, il writer scrive le pagine in streaming e le scarica in ordine; una volta scaricata, una pagina non può più essere disegnata. Il buffer di pagina mantenuto è l’opt-in che trattiene le pagine scaricate affinché una pagina già scaricata possa essere ripopolata — disegnata su una pagina precedente — prima che il documento venga serializzato. L’uso classico è un totale o un riquadro riepilogativo che puoi collocare solo dopo che le pagine successive sono state disposte.

Installazione

composer require nextpdf/core:^3

Il buffer di pagina mantenuto è incluso nel pacchetto core. Config::withRetainedPageBuffer() e i metodi di ripopolamento di Document sono @since 6.1.0. L’impostazione predefinita resta il writer in streaming. ADR-037, che in precedenza aveva rinviato questa capacità, è ora registrato come implementato.

Panoramica concettuale

Config::withRetainedPageBuffer() fa optare un documento nelle pagine mantenute. Una volta attivo, Document::setActiveBackfillPage(int $pageIndex) reindirizza il disegno a una pagina precedente, già scaricata; Document::endPageBackfill() riporta il disegno alla normale posizione di append. Il contenuto che scrivi tra le due chiamate finisce sulla pagina precedente. Il buffer trattiene le pagine fino a save(), perciò il ripopolamento viene applicato prima che la cross-reference table e il trailer siano scritti (ISO 32000-2 §7.5).

Confine fail-closed — combinazioni rifiutate

Il ripopolamento è un’operazione ad accesso casuale, e diverse funzionalità del documento presuppongono byte in streaming e append-only. Il buffer di pagina mantenuto rifiuta di combinarsi con una qualsiasi di esse, indipendentemente dall’ordine e prima della serializzazione, in modo da non poter mai rompere silenziosamente una firma o una rivendicazione di conformità:

• Una firma digitale.
• PDF taggato (albero della struttura).
• PDF/A.
• Linearizzazione.
• Packing in object stream.
• Cifratura.
• Modalità di rendering CSS Safe.

Un budget di byte non compressi per documento limita quanto il buffer può trattenere; un documento che lo supera fallisce in modo netto invece di consumare memoria illimitata. L’impostazione predefinita in streaming continua a fallire in modo fail-closed nel momento in cui un chiamante tenta uno switch ad accesso casuale senza l’opt-in — attivare il buffer è l’unico modo per ottenere il ripopolamento, ed è incompatibile con le funzionalità sopra per costruzione.

Superficie API

Simbolo	Posizione	Ruolo
Config::withRetainedPageBuffer(bool $enabled = true): self	src/Core/Config.php	Fa optare un documento nel buffer di pagina mantenuto.
Document::setActiveBackfillPage(int $pageIndex): static	src/Core/Document.php	Reindirizza il disegno a una pagina precedente, già scaricata.
Document::endPageBackfill(): static	src/Core/Document.php	Riporta il disegno alla normale posizione di append.

Un tentativo di ripopolamento che viola una combinazione rifiutata solleva un’eccezione di configurazione tipizzata al confine, non un documento corrotto.

Esempio di codice — Avvio rapido

Riserva uno spazio sulla pagina uno, riempi il resto del documento, poi ripopola lo spazio riservato con un valore calcolato alla fine.

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

Esempio di codice — Produzione

Mantieni il buffer spento per qualsiasi documento firmato, taggato, PDF/A, linearizzato, cifrato o con object stream — sono esattamente le combinazioni che il buffer rifiuta. Scegli un percorso in modo esplicito.

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

Casi limite e insidie

• Spento è byte-identico. Con il buffer spento, il writer scrive in streaming come prima.
• Mutuamente esclusivo con firma, tagging, PDF/A, linearizzazione, object stream, cifratura e modalità CSS Safe. Il rifiuto è indipendente dall’ordine e scatta prima della serializzazione. Pianifica il documento per una modalità o per l’altra.
• Un budget di byte fallisce in modo netto. Il buffer mantenuto è limitato; un documento che supera il budget di byte non compressi fallisce invece di crescere senza limite.
• Accoppia le chiamate. Ogni setActiveBackfillPage() dovrebbe essere abbinato a un endPageBackfill() affinché il contenuto successivo venga aggiunto normalmente.
• L’impostazione predefinita in streaming rifiuta l’accesso casuale. Senza l’opt-in, uno switch ad accesso casuale fallisce in modo fail-closed. Il buffer è l’unico percorso supportato.

Prestazioni

Il buffer di pagina mantenuto baratta memoria per la capacità di ripopolamento: trattiene le pagine scaricate fino a save(), limitato dal budget di byte non compressi per documento. Il profilo di memoria piatto del writer in streaming si applica solo con il buffer spento. Il performance_budget (wall_ms: 1500, peak_mb: 128) riflette il tetto di memoria più alto del percorso mantenuto.

Note sulla sicurezza

Il buffer di pagina mantenuto non amplia la superficie di input; cambia quando i byte vengono serializzati, non cosa viene ingerito. Il suo rifiuto di combinarsi con cifratura e firma è una proprietà di sicurezza: un ripopolamento non può mai alterare byte firmati o cifrati a posteriori, perché i due non possono essere abilitati insieme. Il budget di byte limita la memoria contro un documento ostile.

Conformità

Affermazione	Standard	Clausola
Il writer serializza il body, la struttura cross-reference e il trailer al momento del salvataggio.	ISO 32000-2	§7.5

Questa è una capacità di anteprima. NextPDF rifiuta il buffer di ripopolamento per documenti firmati, taggati, PDF/A, linearizzati, cifrati e con object stream, perciò non avanza alcuna rivendicazione di conformità per quei profili attraverso questo percorso. Nessun testo normativo è riprodotto.

Adattatore Compat (TCPDF)

L’adattatore di compatibilità TCPDF espone questa capacità come estensione del costruttore. Costruisci l’adattatore con retainedPageBuffer: true, dopodiché una chiamata setPage() o lastPage() che punta a una pagina precedente delega al ripopolamento di core invece di sollevare la UnsupportedFeatureException dello streaming. Questo argomento del costruttore è un’estensione NextPDF, non una parità con il TCPDF legacy — il TCPDF legacy non ha tale flag. Si applicano gli stessi rifiuti fail-closed. Vedi la pagina retained-page-buffer dell’adattatore compat per i dettagli lato adattatore.

Vedere anche

• Modulo Writer
• Modulo Document
• Modulo Config
• Modulo Linearization