Pro editie

Writer

In het kort

De Writer-module voegt incremental-update-revisies toe aan een PDF en pakt kleine objecten in Object Streams. De incremental writer dwingt een append-only-regel af: bytes die vóór de revisie bestonden, mogen niet veranderen.

Beschikbaarheid en licentie

Deze capaciteit wordt geleverd in NextPDF Pro (nextpdf/pro) en activeert met een licentie-envelop op Pro-niveau. Een deployment zonder die entitlement laadt de klassen van de capaciteit niet. Vergelijk edities en verkrijg een licentie. Er is geen aparte licentievlag per feature; de code wordt geleverd met de Pro-editie.

Installatie

composer require nextpdf/pro:^3

De code bevindt zich onder de NextPDF\Pro\Writer-namespace.

Conceptueel overzicht

Er worden twee capaciteiten geleverd:

IncrementalUpdateWriter schrijft een nieuwe revisie. Het herschrijft de catalogus met samengevoegde entries, voegt een traditionele cross-reference table toe voor de nieuwe en gewijzigde objecten, en schrijft een trailer die naar de vorige revisie linkt. Het dwingt een fail-closed append-only-regel af.
ObjectStreamWriter groepeert kleine objecten in één gecomprimeerde Object Stream. Dit verkleint de cross-reference table-grootte en verbetert de compressie. Het wijst objecten af die de maximale streamgrootte zouden overschrijden, en wijst een lege stream af.

De append-only-regel beschermt bestaande handtekeningen. Elke byte die de buffer vóór de revisie bevatte, moet ongewijzigd op dezelfde positie verschijnen na de revisie. Als een eerdere byte verandert, werpt de writer een fout en produceert het geen uitvoer.

Waarom het zo werkt

De doorslaggevende keuze is waar de append-only-gate zich bevindt. Die zit op writer-niveau, niet alleen in hogere orchestrators, zodat elke huidige en toekomstige aanroeper fail-closed-dekking erft. De controle is een pure prefix-gelijkheidstest: de writer maakt een snapshot van de buffer-prefix vóór het toevoegen en bevestigt daarna dat elke eerdere byte ongewijzigd is. Dit beschermt elke handtekening waarvan de /ByteRange de prefix dekte, want één gewijzigde byte zou die stilzwijgend ongeldig maken. Traditionele cross-reference tables en een /Prev-pointer dragen de nieuwe revisie, want incremental updates moeten toevoegen in plaats van herschrijven. De verificatiekosten zijn lineair in de bestaande prefix, en die kosten worden bewust geaccepteerd: de integriteit van ondertekende bytes weegt zwaarder dan een tweede kopie.

Ontwerpachtergrond: Incremental updates en waarom ze ertoe doen.

Gedragscontract

IncrementalUpdateWriter::writeRevision(...) retourneert de byte-offset van de nieuwe cross-reference table, zodat je verdere revisies kunt aaneenketenen.
De writer verifieert dat de oorspronkelijke prefix byte-gelijk is vóór en na het schrijven. Een divergentie werpt een writer-exception die een append-only-violation-status draagt.
De nieuwe revisie gebruikt een traditionele cross-reference table en een trailer met een /Prev-pointer; het mengen van tables en streams over revisies heen is toegestaan.
ObjectStreamWriter::addObject() werpt een overflow-fout wanneer het toevoegen van een object de maximale streamgrootte zou overschrijden (65.536 bytes ongecomprimeerd voor index plus body).
ObjectStreamWriter::build() werpt een fout wanneer geen objecten zijn toegevoegd; anders retourneert het de gecomprimeerde Object Stream-inhoud.

Codevoorbeeld — Snelstart

Het volgende weerspiegelt de gedocumenteerde publieke API. De repository levert geen uitvoerbaar voorbeeld voor deze module.

use NextPDF\Pro\Writer\ObjectStreamWriter;

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

Codevoorbeeld — Productie

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.

Randgevallen en valkuilen

De append-only-controle kopieert de bestaande prefix. De kosten groeien mee met de grootte van het al geschreven document. Deze kosten zijn opzettelijk en beschermen ondertekende bytes.
De Object Stream-groottelimiet geldt voor de gecombineerde index en body vóór compressie. Groepeer objecten dienovereenkomstig.
Object Streams mogen bepaalde objecttypen niet bevatten (bijvoorbeeld het encryption dictionary). Plaats die als directe indirecte objecten.

Prestaties

De append-only-verificatie is lineair in de grootte van de bestaande documentprefix. Object Stream-packing verkleint de cross-reference-grootte en verbetert de compressie ten koste van één extra compressiepass. Er is geen gepubliceerd doorvoercijfer. Meet met representatieve documenten.

Beveiligingsnotities

De incremental writer is fail-closed. Als een codepad een byte zou veranderen die een eerdere handtekening dekte, werpt de writer een fout in plaats van een document te produceren. Dit beschermt de handtekeningintegriteit voor revisie-geketende workflows. Er wordt geen documentinhoud gelogd.

Conformiteit

De bron annoteert de incremental-update-grammatica en het Object Stream-model in ISO 32000-2 en de revisieketeneisen in het ETSI EN 319 142-1 PAdES-profiel. Omdat het RAG-corpus tijdens het opstellen niet beschikbaar was, herhaalt deze pagina alleen de clausulereferenties die de bron zelf declareert en doet het geen uitspraken over aanvullende externe clausule-identifiers.

Enterprise-grensnotitie

Enterprise voegt hogere-tier-handtekeninglevenscyclusfeatures toe (validatie op lange termijn en vernieuwing) die op gedragsniveau voortbouwen op incremental updates. De Writer-module levert alleen de revisieprimitieve; die hogere-tier-features worden apart gedocumenteerd en zijn niet vereist om een revisie te schrijven.

Core-fallback / alternatief

Zonder Pro gebruik je de basis-writer van NextPDF Core; incremental-update-revisies met de append-only-gate en Object Stream-packing zijn Pro-toevoegingen. Zie /modules/writer/.

Publicatiegrens

Deze pagina documenteert alleen extern waarneembaar gedrag en het ondersteunde publieke API-oppervlak. Interne namespace-paden, helperklassen, mechanismetabellen, runbook-bestandsnamen en ticketprefixen vallen buiten de scope.