Pro Edition

Writer

Auf einen Blick

Das Writer-Modul hängt inkrementelle Update-Revisionen an ein PDF an und packt kleine Objekte in Object Streams. Der inkrementelle Writer erzwingt eine Append-only-Regel: Bytes, die vor der Revision existierten, dürfen sich nicht ändern.

Verfügbarkeit & Lizenzierung

Diese Funktion ist in NextPDF Pro (nextpdf/pro) enthalten und wird mit einer Lizenzhülle der Pro-Stufe aktiviert. Eine Bereitstellung ohne diese Berechtigung lädt die Klassen der Funktion nicht. Editionen vergleichen und Lizenz erwerben. Es gibt kein separates Lizenz-Flag pro Funktion; der Code wird mit der Pro-Edition ausgeliefert.

Installation

composer require nextpdf/pro:^3

Der Code liegt unter dem Namespace NextPDF\Pro\Writer.

Konzeptioneller Überblick

Zwei Fähigkeiten werden bereitgestellt:

IncrementalUpdateWriter schreibt eine neue Revision. Er schreibt den Katalog mit zusammengeführten Einträgen neu, hängt eine traditionelle Cross-Reference-Tabelle für die neuen und geänderten Objekte an und schreibt einen Trailer, der auf die vorherige Revision verlinkt. Er erzwingt eine fail-closed Append-only-Regel.
ObjectStreamWriter gruppiert kleine Objekte in einen einzigen komprimierten Object Stream. Dies reduziert die Größe der Cross-Reference-Tabelle und verbessert die Komprimierung. Er weist Objekte zurück, die die maximale Stream-Größe überschreiten würden, und weist einen leeren Stream zurück.

Die Append-only-Regel schützt bestehende Signaturen. Jedes Byte, das der Puffer vor der Revision hielt, muss nach der Revision unverändert an derselben Position erscheinen. Wenn sich ein früheres Byte ändert, löst der Writer einen Fehler aus und erzeugt keine Ausgabe.

Warum es so funktioniert

Die tragende Entscheidung ist, wo das Append-only-Gate liegt. Es sitzt auf Writer-Ebene, nicht nur in übergeordneten Orchestratoren, sodass jeder gegenwärtige und zukünftige Aufrufer eine fail-closed Abdeckung erbt. Die Prüfung ist ein reiner Präfix-Gleichheitstest: Der Writer erstellt vor dem Anhängen einen Snapshot des Puffer-Präfixes und bestätigt danach, dass jedes frühere Byte unverändert ist. Dies schützt jede Signatur, deren /ByteRange das Präfix abdeckte, da ein einziges verändertes Byte sie stillschweigend ungültig machen würde. Traditionelle Cross-Reference-Tabellen und ein /Prev-Pointer tragen die neue Revision, weil inkrementelle Updates anhängen statt neu schreiben müssen. Die Verifikationskosten sind linear zum bestehenden Präfix, und diese Kosten werden bewusst in Kauf genommen: Die Integrität signierter Bytes rangiert vor einer zweiten Kopie.

Design-Hintergrund: Inkrementelle Updates und warum sie wichtig sind.

Verhaltensvertrag

IncrementalUpdateWriter::writeRevision(...) gibt den Byte-Offset der neuen Cross-Reference-Tabelle zurück, sodass Sie weitere Revisionen verketten können.
Der Writer verifiziert, dass das ursprüngliche Präfix vor und nach dem Schreiben byte-gleich ist. Eine Abweichung löst eine Writer-Ausnahme aus, die einen Append-only-Violation-Zustand trägt.
Die neue Revision nutzt eine traditionelle Cross-Reference-Tabelle und einen Trailer mit einem /Prev-Pointer; das Mischen von Tabellen und Streams über Revisionen hinweg ist erlaubt.
ObjectStreamWriter::addObject() löst einen Overflow-Fehler aus, wenn das Hinzufügen eines Objekts die maximale Stream-Größe überschreiten würde (65.536 Bytes unkomprimiert für Index plus Body).
ObjectStreamWriter::build() löst einen Fehler aus, wenn keine Objekte hinzugefügt wurden; andernfalls gibt er den komprimierten Object-Stream-Inhalt zurück.

Codebeispiel — Schnellstart

Das Folgende spiegelt die dokumentierte öffentliche API wider. Das Repository liefert kein lauffähiges Beispiel für dieses Modul.

use NextPDF\Pro\Writer\ObjectStreamWriter;

$writer = new ObjectStreamWriter();
$writer->addObject(10, $serializedObjectBody);
$objStm = $writer->build();

Codebeispiel — Produktion

use NextPDF\Pro\Writer\IncrementalUpdateWriter;

$newXrefOffset = IncrementalUpdateWriter::writeRevision(
    $buffer,
    $registry,
    $prevXrefOffset,
    $catalogObject,
    $catalogEntries,
    $catalogUpdates,
    $newObjectNumbers,
    $fileId,
);
// A WriterException here means the append-only rule was violated.
// Treat it as a hard failure; do not emit the output.

Sonderfälle & Fallstricke

Die Append-only-Prüfung kopiert das bestehende Präfix. Die Kosten wachsen mit der Größe des bereits geschriebenen Dokuments. Diese Kosten sind beabsichtigt und schützen signierte Bytes.
Die Object-Stream-Größengrenze gilt für den kombinierten Index und Body vor der Komprimierung. Gruppieren Sie Objekte entsprechend.
Object Streams dürfen bestimmte Objekttypen nicht enthalten (zum Beispiel das Verschlüsselungs-Dictionary). Platzieren Sie diese als direkte indirekte Objekte.

Performance

Die Append-only-Verifikation ist linear in der Größe des bestehenden Dokumentpräfixes. Das Object-Stream-Packing reduziert die Cross-Reference-Größe und verbessert die Komprimierung auf Kosten eines zusätzlichen Komprimierungsdurchlaufs. Es gibt keine veröffentlichte Durchsatzangabe. Messen Sie mit repräsentativen Dokumenten.

Sicherheitshinweise

Der inkrementelle Writer ist fail-closed. Wenn ein Code-Pfad ein Byte ändern würde, das eine frühere Signatur abdeckte, löst der Writer einen Fehler aus, statt ein Dokument zu erzeugen. Dies schützt die Signaturintegrität für revisionsverkettete Workflows. Es wird kein Dokumentinhalt protokolliert.

Konformität

Die Quelle annotiert die Inkrementelle-Update-Grammatik und das Object-Stream-Modell in ISO 32000-2 sowie die Anforderungen an die Revisionsverkettung im ETSI EN 319 142-1-PAdES-Profil. Weil der RAG-Korpus zum Zeitpunkt der Erstellung nicht verfügbar war, wiederholt diese Seite nur die Klauselreferenzen, die die Quelle selbst deklariert, und behauptet keine zusätzlichen externen Klauselbezeichner.

Hinweis zur Enterprise-Grenze

Enterprise ergänzt höherstufige Signatur-Lifecycle-Funktionen (Langzeitvalidierung und Erneuerung), die auf inkrementellen Updates auf Verhaltensebene aufbauen. Das Writer-Modul stellt ausschließlich das Revisions-Primitiv bereit; diese höherstufigen Funktionen werden separat dokumentiert und sind nicht erforderlich, um eine Revision zu schreiben.

Core-Fallback / Alternative

Ohne Pro verwenden Sie den Basis-Writer von NextPDF Core; inkrementelle Update-Revisionen mit dem Append-only-Gate und Object-Stream-Packing sind Pro-Ergänzungen. Siehe /modules/writer/.

Publikationsgrenze

Diese Seite dokumentiert ausschließlich extern beobachtbares Verhalten und die unterstützte öffentliche API-Oberfläche. Interne Namespace-Pfade, Hilfsklassen, Mechanismus-Tabellen, Runbook-Dateinamen und Ticket-Präfixe sind außerhalb des Geltungsbereichs.