Writer

De un vistazo

El módulo Writer anexa revisiones de actualización incremental a un PDF y empaqueta objetos pequeños en Object Streams. El writer incremental impone una regla de solo anexado: los bytes que existían antes de la revisión no deben cambiar.

Disponibilidad y licenciamiento

Esta capacidad se incluye en NextPDF Pro (nextpdf/pro) y se activa con un sobre de licencia de nivel Pro. Una implementación sin esa habilitación no carga las clases de la capacidad. Compare ediciones y obtenga una licencia. No existe ningún indicador de licencia por característica independiente; el código se incluye con la edición Pro.

Instalación

composer require nextpdf/pro:^3

El código reside bajo el espacio de nombres NextPDF\Pro\Writer.

Descripción conceptual

Se proporcionan dos capacidades:

• IncrementalUpdateWriter escribe una nueva revisión. Vuelve a escribir el catálogo con las entradas fusionadas, anexa una tabla de referencias cruzadas tradicional para los objetos nuevos y modificados, y escribe un tráiler que enlaza con la revisión anterior. Impone una regla de solo anexado de fallo cerrado.
• ObjectStreamWriter agrupa objetos pequeños en un único Object Stream comprimido. Esto reduce el tamaño de la tabla de referencias cruzadas y mejora la compresión. Rechaza los objetos que superarían el tamaño máximo de flujo y rechaza un flujo vacío.

La regla de solo anexado protege las firmas existentes. Cada byte que el búfer contenía antes de la revisión debe aparecer sin cambios en la misma posición tras la revisión. Si algún byte anterior cambia, el writer lanza un error y no produce salida.

Por qué funciona así

La decisión determinante es dónde reside la compuerta de solo anexado. Se sitúa en el ámbito del writer, no solo en los orquestadores de nivel superior, de modo que todo llamador presente y futuro hereda una cobertura de fallo cerrado. La comprobación es una prueba pura de igualdad de prefijo: el writer captura una instantánea del prefijo del búfer antes de anexar y luego confirma que cada byte anterior permanece sin cambios después. Esto protege cualquier firma cuyo /ByteRange cubriera el prefijo, ya que un solo byte alterado la invalidaría de forma silenciosa. Las tablas de referencias cruzadas tradicionales y un puntero /Prev transportan la nueva revisión, porque las actualizaciones incrementales deben anexar en lugar de reescribir. El costo de verificación es lineal respecto al prefijo existente, y ese costo se acepta de forma deliberada: la integridad de los bytes firmados prevalece sobre una segunda copia.

Contexto de diseño: Actualizaciones incrementales y por qué importan.

Contrato de comportamiento

• IncrementalUpdateWriter::writeRevision(...) devuelve el desplazamiento en bytes de la nueva tabla de referencias cruzadas, para que pueda encadenar revisiones posteriores.
• El writer verifica que el prefijo original sea idéntico byte a byte antes y después de escribir. Una divergencia lanza una excepción del writer que transporta un estado de violación de solo anexado.
• La nueva revisión usa una tabla de referencias cruzadas tradicional y un tráiler con un puntero /Prev; se permite mezclar tablas y flujos entre revisiones.
• ObjectStreamWriter::addObject() lanza un error de desbordamiento cuando añadir un objeto superaría el tamaño máximo de flujo (65.536 bytes sin comprimir para el índice más el cuerpo).
• ObjectStreamWriter::build() lanza un error cuando no se añadió ningún objeto; de lo contrario, devuelve el contenido comprimido del Object Stream.

Ejemplo de código — Inicio rápido

A continuación se refleja la API pública documentada. El repositorio no incluye un ejemplo ejecutable para este módulo.

use NextPDF\Pro\Writer\ObjectStreamWriter;

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

Ejemplo de código — Producción

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.

Casos límite y trampas

• La comprobación de solo anexado copia el prefijo existente. El costo crece con el tamaño del documento ya escrito. Este costo es intencionado y protege los bytes firmados.
• El límite de tamaño del Object Stream se aplica al índice y al cuerpo combinados antes de la compresión. Agrupe los objetos en consecuencia.
• Los Object Streams no deben contener ciertos tipos de objeto (por ejemplo, el diccionario de cifrado). Coloque esos como objetos indirectos directos.

Rendimiento

La verificación de solo anexado es lineal en el tamaño del prefijo del documento existente. El empaquetado en Object Stream reduce el tamaño de las referencias cruzadas y mejora la compresión a costa de una pasada de compresión adicional. No hay ninguna cifra de rendimiento publicada. Mida con documentos representativos.

Notas de seguridad

El writer incremental es de fallo cerrado. Si una ruta de código cambiaría un byte que una firma anterior cubría, el writer lanza un error en lugar de producir un documento. Esto protege la integridad de la firma en los flujos de trabajo con revisiones encadenadas. No se registra ningún contenido del documento.

Conformidad

El origen anota la gramática de actualización incremental y el modelo de Object Stream en ISO 32000-2 y los requisitos de encadenamiento de revisiones del perfil PAdES de ETSI EN 319 142-1. Como el corpus de RAG no estaba disponible en el momento de la redacción, esta página solo repite las referencias de cláusula que el propio origen declara y no afirma ningún identificador de cláusula externo adicional.

Nota sobre el límite de Enterprise

Enterprise añade funciones de ciclo de vida de firma de nivel superior (validación a largo plazo y renovación) que se basan en las actualizaciones incrementales a nivel de comportamiento. El módulo Writer proporciona únicamente la primitiva de revisión; esas funciones de nivel superior se documentan por separado y no son necesarias para escribir una revisión.

Alternativa / repliegue de Core

Sin Pro, use el writer básico de NextPDF Core; las revisiones de actualización incremental con la compuerta de solo anexado y el empaquetado en Object Stream son adiciones de Pro. Consulte /modules/writer/.

Límite de publicación

Esta página documenta únicamente el comportamiento observable externamente y la superficie de la API pública admitida. Las rutas de espacio de nombres internas, las clases de ayuda, las tablas de mecanismos, los nombres de archivo de runbook y los prefijos de ticket quedan fuera de alcance.

Véase también

• Writer — Referencia detallada
• Documento
• Optimizador
• Pipeline de salida