Pro édition

Writer

En bref

Le module Writer ajoute des révisions par mise à jour incrémentale à un PDF et empaquette les petits objets dans des Object Stream. Le writer incrémental impose une règle d’ajout seul : les octets qui existaient avant la révision ne doivent pas changer.

Disponibilité et licence

Cette capacité est fournie dans NextPDF Pro (nextpdf/pro) et s’active avec une enveloppe de licence de palier Pro. Un déploiement dépourvu de ce droit ne charge pas les classes de la capacité. Compare les éditions et obtiens une licence. Il n’y a pas d’indicateur de licence distinct par fonctionnalité ; le code est livré avec l’édition Pro.

Installation

composer require nextpdf/pro:^3

Le code se trouve sous l’espace de noms NextPDF\Pro\Writer.

Aperçu conceptuel

Deux capacités sont fournies :

IncrementalUpdateWriter écrit une nouvelle révision. Il réécrit le catalogue avec les entrées fusionnées, ajoute une table de références croisées traditionnelle pour les objets nouveaux et modifiés, et écrit un trailer qui pointe vers la révision précédente. Il impose une règle d’ajout seul fermée en cas d’échec.
ObjectStreamWriter regroupe les petits objets dans un seul Object Stream compressé. Cela réduit la taille de la table de références croisées et améliore la compression. Il rejette les objets qui dépasseraient la taille maximale du flux et rejette un flux vide.

La règle d’ajout seul protège les signatures existantes. Chaque octet que le tampon contenait avant la révision doit apparaître inchangé à la même position après la révision. Si un octet antérieur change, le writer lève une erreur et ne produit pas de sortie.

Pourquoi cela fonctionne ainsi

Le choix porteur est l’emplacement de la barrière d’ajout seul. Elle se situe à la portée du writer, et pas uniquement dans les orchestrateurs de plus haut niveau, de sorte que chaque appelant présent et futur hérite d’une couverture fermée en cas d’échec. La vérification est un pur test d’égalité de préfixe : le writer prend un instantané du préfixe du tampon avant l’ajout, puis confirme ensuite que chaque octet antérieur est inchangé. Cela protège toute signature dont le /ByteRange couvrait le préfixe, car un seul octet altéré l’invaliderait silencieusement. Des tables de références croisées traditionnelles et un pointeur /Prev portent la nouvelle révision, car les mises à jour incrémentales doivent ajouter plutôt que réécrire. Le coût de vérification est linéaire en taille du préfixe existant, et ce coût est accepté délibérément : l’intégrité des octets signés prime sur une seconde copie.

Contexte de conception : Les mises à jour incrémentales et pourquoi elles comptent.

Contrat de comportement

IncrementalUpdateWriter::writeRevision(...) renvoie l’offset en octets de la nouvelle table de références croisées, afin que tu puisses chaîner d’autres révisions.
Le writer vérifie que le préfixe d’origine est égal octet par octet avant et après l’écriture. Une divergence lève une exception de writer qui porte un état de violation d’ajout seul.
La nouvelle révision utilise une table de références croisées traditionnelle et un trailer avec un pointeur /Prev ; mélanger les tables et les flux entre révisions est permis.
ObjectStreamWriter::addObject() lève une erreur de dépassement lorsque l’ajout d’un objet dépasserait la taille maximale du flux (65 536 octets non compressés pour l’index plus le corps).
ObjectStreamWriter::build() lève une erreur lorsqu’aucun objet n’a été ajouté ; sinon il renvoie le contenu compressé de l’Object Stream.

Exemple de code — Démarrage rapide

Ce qui suit reflète l’API publique documentée. Le dépôt ne livre pas d’exemple exécutable pour ce module.

use NextPDF\Pro\Writer\ObjectStreamWriter;

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

Exemple de code — Production

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.

Cas limites et pièges

La vérification d’ajout seul copie le préfixe existant. Le coût croît avec la taille du document déjà écrit. Ce coût est intentionnel et protège les octets signés.
La limite de taille de l’Object Stream porte sur l’index et le corps combinés avant compression. Regroupe les objets en conséquence.
Les Object Stream ne doivent pas contenir certains types d’objets (par exemple, le dictionnaire de chiffrement). Place-les en tant qu’objets indirects directs.

Performance

La vérification d’ajout seul est linéaire en taille du préfixe de document existant. L’empaquetage en Object Stream réduit la taille des références croisées et améliore la compression au prix d’une passe de compression supplémentaire. Il n’y a pas de chiffre de débit publié. Mesure avec des documents représentatifs.

Notes de sécurité

Le writer incrémental est fermé en cas d’échec. Si un chemin de code devait changer un octet couvert par une signature antérieure, le writer lève une erreur au lieu de produire un document. Cela protège l’intégrité de la signature pour les flux à révisions chaînées. Aucun contenu de document n’est journalisé.

Conformité

La source annote la grammaire de mise à jour incrémentale et le modèle d’Object Stream dans ISO 32000-2, ainsi que les exigences de chaînage de révisions dans le profil PAdES ETSI EN 319 142-1. Comme le corpus RAG était indisponible au moment de la rédaction, cette page ne reprend que les références de clause que la source déclare elle-même et n’affirme aucun identifiant de clause externe supplémentaire.

Note sur la frontière Enterprise

Enterprise ajoute des fonctionnalités de cycle de vie de signature de palier supérieur (validation et renouvellement à long terme) qui s’appuient sur les mises à jour incrémentales au niveau du comportement. Le module Writer fournit uniquement la primitive de révision ; ces fonctionnalités de palier supérieur sont documentées séparément et ne sont pas requises pour écrire une révision.

Repli / alternative Core

Sans Pro, utilise le writer de base de NextPDF Core ; les révisions par mise à jour incrémentale avec la barrière d’ajout seul et l’empaquetage en Object Stream sont des ajouts de Pro. Voir /modules/writer/.

Frontière de publication

Cette page ne documente que le comportement observable de l’extérieur et la surface d’API publique prise en charge. Les chemins d’espaces de noms internes, les classes utilitaires, les tables de mécanismes, les noms de fichiers de runbook et les préfixes de tickets sont hors périmètre.