Writer

한눈에 보기

Writer 모듈은 증분 업데이트(incremental-update) 리비전을 PDF에 추가하고 작은 객체를 Object Stream으로 묶습니다. 증분 writer는 추가 전용(append-only) 규칙을 강제합니다. 리비전 이전에 존재한 바이트는 변경되어서는 안 됩니다.

가용성 및 라이선싱

이 기능은 NextPDF Pro(nextpdf/pro)로 제공되며 Pro 등급 라이선스 엔벨로프로 활성화됩니다. 해당 권한이 없는 배포 환경은 이 기능의 클래스를 로드하지 않습니다. 에디션 비교 및 라이선스 받기. 별도의 기능별 라이선스 플래그는 없습니다. 코드는 Pro 에디션과 함께 제공됩니다.

설치

composer require nextpdf/pro:^3

코드는 NextPDF\Pro\Writer 네임스페이스 아래에 있습니다.

개념 개요

두 가지 기능이 제공됩니다.

• IncrementalUpdateWriter는 새 리비전을 작성합니다. 병합된 항목으로 카탈로그를 다시 작성하고, 새 객체 및 수정된 객체에 대한 전통적 상호 참조 테이블을 추가하며, 이전 리비전으로 연결되는 트레일러를 작성합니다. 실패-차단 추가 전용 규칙을 강제합니다.
• ObjectStreamWriter는 작은 객체를 단일 압축 Object Stream으로 그룹화합니다. 이는 상호 참조 테이블 크기를 줄이고 압축을 개선합니다. 최대 스트림 크기를 초과하게 될 객체를 거부하고 빈 스트림을 거부합니다.

추가 전용 규칙은 기존 서명을 보호합니다. 리비전 이전에 버퍼가 담고 있던 모든 바이트는 리비전 이후에도 동일한 위치에 변경되지 않은 채로 나타나야 합니다. 더 앞선 바이트가 하나라도 변경되면, writer는 오류를 발생시키고 출력을 생성하지 않습니다.

이렇게 동작하는 이유

핵심적인 선택은 추가 전용 게이트가 위치하는 지점입니다. 이 게이트는 상위 수준 오케스트레이터에만 두지 않고 writer 범위에 두어, 현재와 미래의 모든 호출자가 실패-차단 커버리지를 상속받도록 합니다. 이 검사는 순수한 접두사 동등성 테스트입니다. writer는 추가하기 전에 버퍼 접두사(prefix)의 스냅샷을 찍고, 이후에 더 앞선 모든 바이트가 변경되지 않았음을 확인합니다. 이는 /ByteRange가 접두사를 포괄한 모든 서명을 보호합니다. 바이트 하나만 변경되어도 서명이 조용히 무효화되기 때문입니다. 증분 업데이트는 다시 쓰는 것이 아니라 추가해야 하므로, 전통적 상호 참조 테이블과 /Prev 포인터가 새 리비전을 담습니다. 검증 비용은 기존 접두사에 선형적이며, 그 비용은 의도적으로 수용됩니다. 서명된 바이트의 무결성이 사본 하나보다 우선하기 때문입니다.

설계 배경: 증분 업데이트와 그것이 중요한 이유.

동작 계약

• IncrementalUpdateWriter::writeRevision(...)는 새 상호 참조 테이블의 바이트 오프셋을 반환하므로, 추가 리비전을 체이닝할 수 있습니다.
• writer는 작성 전과 후에 원본 접두사가 바이트 단위로 동일한지 검증합니다. 차이가 발생하면 추가 전용 위반(append-only-violation) 상태를 담은 writer 예외를 발생시킵니다.
• 새 리비전은 전통적 상호 참조 테이블과 /Prev 포인터가 있는 트레일러를 사용합니다. 리비전 간에 테이블과 스트림을 혼합하는 것은 허용됩니다.
• ObjectStreamWriter::addObject()는 객체를 추가하면 최대 스트림 크기(인덱스와 본문에 대해 비압축 65,536바이트)를 초과하게 될 때 오버플로 오류를 발생시킵니다.
• ObjectStreamWriter::build()는 추가된 객체가 없을 때 오류를 발생시킵니다. 그렇지 않으면 압축된 Object Stream 콘텐츠를 반환합니다.

코드 샘플 — 빠른 시작

다음은 문서화된 공개 API를 반영합니다. 리포지터리는 이 모듈에 대한 실행 가능한 예제를 제공하지 않습니다.

use NextPDF\Pro\Writer\ObjectStreamWriter;

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

코드 샘플 — 프로덕션

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.

엣지 케이스 및 함정

• 추가 전용 검사는 기존 접두사를 복사합니다. 그 비용은 이미 작성된 문서의 크기에 따라 증가합니다. 이 비용은 의도된 것이며 서명된 바이트를 보호합니다.
• Object Stream 크기 한계는 압축 이전의 결합된 인덱스와 본문에 적용됩니다. 객체를 그에 맞게 그룹화하십시오.
• Object Stream은 특정 객체 타입(예: 암호화 딕셔너리)을 포함해서는 안 됩니다. 그러한 객체는 직접 간접 객체(direct indirect objects)로 배치하십시오.

성능

추가 전용 검증은 기존 문서 접두사의 크기에 선형적입니다. Object Stream 묶음은 상호 참조 크기를 줄이고 압축을 개선하지만, 압축 패스 1회가 추가되는 비용이 따릅니다. 발행된 처리량 수치는 없습니다. 대표 문서로 측정하십시오.

보안 참고

증분 writer는 실패-차단됩니다. 코드 경로가 더 앞선 서명이 포괄한 바이트를 변경하려 하면, writer는 문서를 생성하는 대신 오류를 발생시킵니다. 이는 리비전 체이닝 워크플로의 서명 무결성을 보호합니다. 어떤 문서 콘텐츠도 로그에 기록되지 않습니다.

적합성

소스는 ISO 32000-2의 증분 업데이트 문법과 Object Stream 모델, 그리고 ETSI EN 319 142-1 PAdES 프로파일의 리비전 체이닝 요구 사항을 주석으로 표기합니다. 작성 시점에 RAG 코퍼스를 사용할 수 없었으므로, 이 페이지는 소스 자체가 선언한 조항 참조만 반복하며 추가 외부 조항 식별자를 주장하지 않습니다.

Enterprise 경계 참고

Enterprise는 증분 업데이트 위에 동작 수준에서 구축되는 상위 등급 서명 수명 주기 기능(장기 검증 및 갱신)을 더합니다. Writer 모듈은 리비전 프리미티브만 제공합니다. 그러한 상위 등급 기능은 별도로 문서화되며 리비전을 작성하는 데 필요하지 않습니다.

Core 폴백 / 대안

Pro 없이는 NextPDF Core의 기본 writer를 사용하십시오. 추가 전용 게이트가 있는 증분 업데이트 리비전과 Object Stream 묶음은 Pro 추가 기능입니다. /modules/writer/를 참고하십시오.

발행 경계

이 페이지는 외부에서 관찰 가능한 동작과 지원되는 공개 API 표면만 설명합니다. 내부 네임스페이스 경로, 헬퍼 클래스, 메커니즘 테이블, 런북 파일명, 티켓 접두사는 범위에 포함되지 않습니다.

함께 보기

• Writer — 심화 레퍼런스
• Document
• Optimizer
• Output Pipeline