PageBackfill: Retained Page Buffer

Auf einen Blick

Per Opt-in aktivierbare Vorschau. Der Retained Page Buffer ist standardmäßig aus. Ist er aus, ist der Writer der streamende Serialisierer, der er immer war — byte-identisch. Schalten Sie ihn nur ein, wenn Sie wirklich auf eine frühere Seite zeichnen müssen, und lesen Sie zuerst die Fail-closed-Liste unten.

Standardmäßig streamt der Writer Seiten und flusht sie in Reihenfolge; sobald eine Seite geflusht ist, kann nicht mehr auf sie gezeichnet werden. Der Retained Page Buffer ist das Opt-in, das geflushte Seiten hält, sodass eine zuvor geflushte Seite nachgefüllt werden kann — auf eine frühere Seite gezeichnet — bevor das Dokument serialisiert wird. Der klassische Einsatz ist eine Summe oder eine Übersichtsbox, die Sie erst platzieren können, nachdem spätere Seiten umbrochen wurden.

Installation

composer require nextpdf/core:^3

Der Retained Page Buffer wird im Core-Paket ausgeliefert. Config::withRetainedPageBuffer() und die Document-Nachfüllmethoden sind @since 6.1.0. Der Standard bleibt der streamende Writer. ADR-037, das diese Fähigkeit zuvor zurückgestellt hatte, ist nun als implementiert verzeichnet.

Konzeptioneller Überblick

Config::withRetainedPageBuffer() aktiviert für ein Dokument gehaltene Seiten. Ist es aktiv, leitet Document::setActiveBackfillPage(int $pageIndex) das Zeichnen auf eine frühere, bereits geflushte Seite um; Document::endPageBackfill() führt das Zeichnen an die normale Anhängeposition zurück. Inhalt, den Sie zwischen den beiden Aufrufen schreiben, landet auf der früheren Seite. Der Puffer hält die Seiten bis save(), sodass die Nachfüllung angewendet wird, bevor die Cross-Reference-Tabelle und der Trailer geschrieben werden (ISO 32000-2 §7.5).

Fail-closed-Grenze — verweigerte Kombinationen

Die Nachfüllung ist eine Random-Access-Operation, und mehrere Dokumentfunktionen setzen append-only, gestreamte Bytes voraus. Der Retained Page Buffer verweigert die Kombination mit jeder von ihnen, reihenfolgeunabhängig und vor der Serialisierung, sodass er nie stillschweigend eine Signatur oder eine Konformitätsaussage brechen kann:

• Eine digitale Signatur.
• Tagged PDF (Strukturbaum).
• PDF/A.
• Linearisierung.
• Object-Stream-Packing.
• Verschlüsselung.
• Safe-CSS-Rendering-Modus.

Ein Budget für unkomprimierte Bytes pro Dokument deckelt, wie viel der Puffer halten darf; ein Dokument, das es überschreitet, schlägt hart fehl, statt unbegrenzten Speicher zu verbrauchen. Der Streaming-Standard schlägt weiterhin fail-closed fehl, sobald ein Aufrufer einen Random-Access-Wechsel ohne das Opt-in versucht — den Puffer einzuschalten ist der einzige Weg zur Nachfüllung, und sie ist konstruktionsbedingt mit den oben genannten Funktionen inkompatibel.

API-Oberfläche

Symbol	Ort	Rolle
Config::withRetainedPageBuffer(bool $enabled = true): self	src/Core/Config.php	Aktiviert für ein Dokument den Retained Page Buffer.
Document::setActiveBackfillPage(int $pageIndex): static	src/Core/Document.php	Leitet das Zeichnen auf eine frühere, bereits geflushte Seite um.
Document::endPageBackfill(): static	src/Core/Document.php	Führt das Zeichnen an die normale Anhängeposition zurück.

Ein Nachfüllversuch, der eine verweigerte Kombination verletzt, löst an der Grenze eine typisierte Konfigurationsausnahme aus, kein korruptes Dokument.

Codebeispiel — Schnellstart

Reservieren Sie einen Platz auf Seite eins, füllen Sie den Rest des Dokuments und füllen Sie dann den reservierten Platz mit einem am Ende berechneten Wert nach.

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

Codebeispiel — Produktion

Halten Sie den Puffer aus für jedes signierte, getaggte, PDF/A-, linearisierte, verschlüsselte oder Object-Stream-Dokument — das sind genau die Kombinationen, die der Puffer verweigert. Wählen Sie einen Pfad explizit.

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

Randfälle & Fallstricke

• Aus ist byte-identisch. Ist der Puffer aus, streamt der Writer wie zuvor.
• Gegenseitig ausschließend mit Signieren, Tagging, PDF/A, Linearisierung, Object Streams, Verschlüsselung und Safe-CSS-Modus. Die Verweigerung ist reihenfolgeunabhängig und feuert vor der Serialisierung. Planen Sie das Dokument für den einen oder den anderen Modus.
• Ein Byte-Budget schlägt hart fehl. Der Retained Buffer ist begrenzt; ein Dokument, das das Budget für unkomprimierte Bytes überschreitet, schlägt fehl, statt unbegrenzt zu wachsen.
• Paaren Sie die Aufrufe. Jedes setActiveBackfillPage() sollte durch ein endPageBackfill() ergänzt werden, sodass späterer Inhalt normal angehängt wird.
• Der Streaming-Standard verweigert Random Access. Ohne das Opt-in schlägt ein Random-Access-Wechsel fail-closed fehl. Der Puffer ist der einzige unterstützte Pfad.

Performance

Der Retained Page Buffer tauscht Speicher gegen die Nachfüllfähigkeit: Er hält geflushte Seiten bis save(), begrenzt durch das Budget für unkomprimierte Bytes pro Dokument. Das flache Speicherprofil des streamenden Writers gilt nur bei ausgeschaltetem Puffer. Das performance_budget (wall_ms: 1500, peak_mb: 128) spiegelt die höhere Speicherobergrenze des Retained-Pfads wider.

Sicherheitshinweise

Der Retained Page Buffer weitet die Eingabeoberfläche nicht aus; er ändert, wann Bytes serialisiert werden, nicht, was ingestiert wird. Seine Verweigerung der Kombination mit Verschlüsselung und Signieren ist eine Sicherheitseigenschaft: Eine Nachfüllung kann nie signierte oder verschlüsselte Bytes nachträglich verändern, weil sich die beiden nicht gemeinsam aktivieren lassen. Das Byte-Budget begrenzt den Speicher gegenüber einem feindseligen Dokument.

Konformität

Aussage	Standard	Klausel
Der Writer serialisiert den Body, die Cross-Reference-Struktur und den Trailer zum Speicherzeitpunkt.	ISO 32000-2	§7.5

Dies ist eine Vorschau-Fähigkeit. NextPDF verweigert den Backfill-Puffer für signierte, getaggte, PDF/A-, linearisierte, verschlüsselte und Object-Stream-Dokumente, sodass über diesen Pfad keine Konformitätsaussage für diese Profile gemacht wird. Es wird kein Standardtext wiedergegeben.

Compat-(TCPDF)-Adapter

Der TCPDF-Kompatibilitätsadapter stellt diese Fähigkeit als Konstruktor-Erweiterung bereit. Konstruieren Sie den Adapter mit retainedPageBuffer: true, dann delegiert ein setPage()- oder lastPage()-Aufruf, der auf eine frühere Seite zielt, an die Core-Nachfüllung, statt die streamende UnsupportedFeatureException auszulösen. Dieses Konstruktor-Argument ist eine NextPDF-Erweiterung, keine Legacy-TCPDF-Parität — Legacy-TCPDF hat kein solches Flag. Dieselben Fail-closed-Verweigerungen gelten. Siehe die Retained-Page-Buffer-Seite des Compat-Adapters für die adapterseitigen Details.

Siehe auch

• Writer-Modul
• Document-Modul
• Config-Modul
• Linearisierungs-Modul