Writer

In breve

Il modulo Writer appende revisioni di incremental update a un PDF e impacchetta piccoli oggetti negli Object Stream. Il writer incrementale impone una regola append-only: i byte che esistevano prima della revisione non devono cambiare.

Disponibilità e licenza

Questa capability è distribuita in NextPDF Pro (nextpdf/pro) e si attiva con un envelope di licenza di livello Pro. Un deployment privo di tale entitlement non carica le classi della capability. Confronta le edizioni e ottieni una licenza. Non esiste un flag di licenza separato per singola funzionalità; il codice è distribuito con l’edizione Pro.

Installazione

composer require nextpdf/pro:^3

Il codice risiede sotto il namespace NextPDF\Pro\Writer.

Panoramica concettuale

Vengono fornite due capability:

• IncrementalUpdateWriter scrive una nuova revisione. Riscrive il catalogo con le voci unite, appende una tabella di cross-reference tradizionale per gli oggetti nuovi e modificati e scrive un trailer che collega alla revisione precedente. Impone una regola append-only fail-closed.
• ObjectStreamWriter raggruppa piccoli oggetti in un singolo Object Stream compresso. Ciò riduce la dimensione della tabella di cross-reference e migliora la compressione. Rifiuta gli oggetti che supererebbero la dimensione massima dello stream e rifiuta uno stream vuoto.

La regola append-only protegge le firme esistenti. Ogni byte che il buffer conteneva prima della revisione deve comparire invariato nella stessa posizione dopo la revisione. Se un qualsiasi byte precedente cambia, il writer solleva un errore e non produce output.

Perché funziona così

La scelta portante è dove risiede il gate append-only. Si colloca a livello di writer, non solo negli orchestratori di livello superiore, così ogni chiamante presente e futuro eredita una copertura fail-closed. La verifica è un puro test di uguaglianza del prefisso: il writer acquisisce uno snapshot del prefisso del buffer prima di appendere, poi conferma che ogni byte precedente sia invariato dopo. Ciò protegge qualsiasi firma il cui /ByteRange copriva il prefisso, poiché un solo byte alterato la invaliderebbe silenziosamente. Tabelle di cross-reference tradizionali e un puntatore /Prev trasportano la nuova revisione, perché gli incremental update devono appendere anziché riscrivere. Il costo di verifica è lineare nel prefisso esistente, e tale costo è accettato deliberatamente: l’integrità dei byte firmati prevale su una seconda copia.

Contesto di progettazione: Gli incremental update e perché contano.

Contratto di comportamento

• IncrementalUpdateWriter::writeRevision(...) restituisce l’offset di byte della nuova tabella di cross-reference, così da poter concatenare ulteriori revisioni.
• Il writer verifica che il prefisso originale sia uguale byte per byte prima e dopo la scrittura. Una divergenza solleva un’eccezione del writer che trasporta uno stato di violazione append-only.
• La nuova revisione usa una tabella di cross-reference tradizionale e un trailer con un puntatore /Prev; è consentito mescolare tabelle e stream tra le revisioni.
• ObjectStreamWriter::addObject() solleva un errore di overflow quando l’aggiunta di un oggetto supererebbe la dimensione massima dello stream (65.536 byte non compressi per indice più corpo).
• ObjectStreamWriter::build() solleva un errore quando non sono stati aggiunti oggetti; in caso contrario restituisce il contenuto dell’Object Stream compresso.

Esempio di codice — Avvio rapido

Quanto segue riflette l’API pubblica documentata. Il repository non distribuisce un esempio eseguibile per questo modulo.

use NextPDF\Pro\Writer\ObjectStreamWriter;

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

Esempio di codice — Produzione

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.

Casi limite e accorgimenti

• La verifica append-only copia il prefisso esistente. Il costo cresce con la dimensione del documento già scritto. Questo costo è intenzionale e protegge i byte firmati.
• Il limite di dimensione dell’Object Stream è sull’indice e sul corpo combinati prima della compressione. Raggruppare gli oggetti di conseguenza.
• Gli Object Stream non devono contenere determinati tipi di oggetto (ad esempio, il dizionario di cifratura). Collocare questi come oggetti indiretti diretti.

Prestazioni

La verifica append-only è lineare nella dimensione del prefisso del documento esistente. L’impacchettamento degli Object Stream riduce la dimensione della cross-reference e migliora la compressione al costo di una passata di compressione aggiuntiva. Non esiste alcuna cifra di throughput pubblicata. Misurare con documenti rappresentativi.

Note di sicurezza

Il writer incrementale è fail-closed. Se un percorso di codice cambiasse un byte coperto da una firma precedente, il writer solleva un errore anziché produrre un documento. Ciò protegge l’integrità della firma per i flussi di lavoro a revisioni concatenate. Nessun contenuto del documento viene registrato.

Conformità

Il sorgente annota la grammatica dell’incremental update e il modello degli Object Stream in ISO 32000-2 e i requisiti di concatenamento delle revisioni nel profilo PAdES ETSI EN 319 142-1. Poiché il corpus RAG non era disponibile al momento della redazione, questa pagina ripete solo i riferimenti di clausola che il sorgente stesso dichiara e non asserisce alcun identificatore di clausola esterno aggiuntivo.

Nota sul confine Enterprise

Enterprise aggiunge funzionalità di ciclo di vita della firma di livello superiore (validazione a lungo termine e rinnovo) che si fondano sugli incremental update a livello di comportamento. Il modulo Writer fornisce solo la primitiva di revisione; quelle funzionalità di livello superiore sono documentate separatamente e non sono richieste per scrivere una revisione.

Fallback / alternativa di Core

Senza Pro, usare il writer di base di NextPDF Core; le revisioni di incremental update con il gate append-only e l’impacchettamento degli Object Stream sono aggiunte di Pro. Vedere /modules/writer/.

Confine di pubblicazione

Questa pagina documenta solo il comportamento osservabile dall’esterno e la superficie dell’API pubblica supportata. Percorsi di namespace interni, classi helper, tabelle dei meccanismi, nomi di file dei runbook e prefissi dei ticket sono fuori ambito.

Vedere anche

• Writer — Riferimento approfondito
• Document
• Optimizer
• Output Pipeline