Pro sürüm

Writer

Bir bakışta

Writer modülü, bir PDF’ye artımlı güncelleme düzeltmeleri ekler ve küçük nesneleri Object Stream’lere paketler. Artımlı yazıcı, yalnızca-ekleme kuralını zorunlu kılar: düzeltmeden önce var olan baytlar değişmemelidir.

Kullanılabilirlik ve lisanslama

Bu yetenek NextPDF Pro (nextpdf/pro) ile birlikte gelir ve bir Pro katmanı lisans zarfıyla etkinleşir. Bu yetkilendirmeye sahip olmayan bir dağıtım, yeteneğin sınıflarını yüklemez. Sürümleri karşılaştırın ve bir lisans edinin. Özellik başına ayrı bir lisans bayrağı yoktur; kod Pro sürümüyle birlikte gelir.

Kurulum

composer require nextpdf/pro:^3

Kod, NextPDF\Pro\Writer ad alanı altında yer alır.

Kavramsal genel bakış

İki yetenek sağlanır:

IncrementalUpdateWriter, yeni bir düzeltme yazar. Kataloğu birleştirilmiş girdilerle yeniden yazar, yeni ve değiştirilmiş nesneler için geleneksel bir çapraz başvuru tablosu ekler ve önceki düzeltmeye bağlanan bir fragman yazar. Kapalı başarısız bir yalnızca-ekleme kuralını zorunlu kılar.
ObjectStreamWriter, küçük nesneleri tek bir sıkıştırılmış Object Stream içinde gruplar. Bu, çapraz başvuru tablosu boyutunu azaltır ve sıkıştırmayı iyileştirir. Maksimum akış boyutunu aşacak nesneleri reddeder ve boş bir akışı reddeder.

Yalnızca-ekleme kuralı, mevcut imzaları korur. Arabelleğin düzeltmeden önce tuttuğu her bayt, düzeltmeden sonra aynı konumda değişmeden görünmelidir. Daha önceki herhangi bir bayt değişirse, yazıcı bir hata oluşturur ve çıktı üretmez.

Neden bu şekilde çalışır

Yük taşıyan tercih, yalnızca-ekleme kapısının nerede bulunduğudur. Yalnızca daha üst düzey düzenleyicilerde değil, yazıcı kapsamında yer alır; böylece mevcut ve gelecekteki her çağıran, kapalı başarısız kapsamı devralır. Denetim, saf bir önek eşitliği testidir: yazıcı, eklemeden önce arabellek önekinin anlık görüntüsünü alır, ardından her daha önceki baytın sonrasında değişmediğini doğrular. Bu, /ByteRange değeri öneki kapsayan herhangi bir imzayı korur; çünkü değiştirilen tek bir bayt onu sessizce geçersiz kılardı. Artımlı güncellemeler yeniden yazmak yerine eklemek zorunda olduğundan, yeni düzeltmeyi geleneksel çapraz başvuru tabloları ve bir /Prev işaretçisi taşır. Doğrulama maliyeti mevcut önekle doğrusaldır ve bu maliyet bilinçli olarak kabul edilir: imzalı bayt bütünlüğü, ikinci bir kopyadan üstündür.

Tasarım arka planı: Artımlı güncellemeler ve neden önemli oldukları.

Davranış sözleşmesi

IncrementalUpdateWriter::writeRevision(...), yeni çapraz başvuru tablosunun bayt ofsetini döndürür; böylece başka düzeltmeleri zincirleyebilirsiniz.
Yazıcı, özgün önekin yazmadan önce ve sonra bayt düzeyinde eşit olduğunu doğrular. Bir sapma, bir yalnızca-ekleme-ihlali durumu taşıyan bir yazıcı istisnası oluşturur.
Yeni düzeltme, geleneksel bir çapraz başvuru tablosu ve bir /Prev işaretçili bir fragman kullanır; düzeltmeler arasında tabloların ve akışların karıştırılmasına izin verilir.
ObjectStreamWriter::addObject(), bir nesne eklemek maksimum akış boyutunu (dizin artı gövde için sıkıştırılmamış 65.536 bayt) aşacağında bir taşma hatası oluşturur.
ObjectStreamWriter::build(), hiçbir nesne eklenmediğinde bir hata oluşturur; aksi hâlde sıkıştırılmış Object Stream içeriğini döndürür.

Kod örneği — hızlı başlangıç

Aşağıdaki, belgelenmiş genel API’yi yansıtır. Depo, bu modül için çalıştırılabilir bir örnek sunmaz.

use NextPDF\Pro\Writer\ObjectStreamWriter;

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

Kod örneği — üretim

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.

Uç durumlar ve tuzaklar

Yalnızca-ekleme denetimi mevcut öneki kopyalar. Maliyet, zaten yazılmış belgenin boyutuyla artar. Bu maliyet kasıtlıdır ve imzalı baytları korur.
Object Stream boyutu sınırı, sıkıştırmadan önce birleştirilmiş dizin ve gövde üzerinedir. Nesneleri buna göre gruplayın.
Object Stream’ler belirli nesne türlerini (örneğin şifreleme sözlüğünü) içermemelidir. Bunları doğrudan dolaylı nesneler olarak yerleştirin.

Performans

Yalnızca-ekleme doğrulaması, mevcut belge önekinin boyutunda doğrusaldır. Object Stream paketleme, bir ek sıkıştırma geçişi pahasına çapraz başvuru boyutunu azaltır ve sıkıştırmayı iyileştirir. Yayımlanmış bir verim rakamı yoktur. Temsili belgelerle ölçün.

Güvenlik notları

Artımlı yazıcı kapalı başarısızdır. Bir kod yolu, daha önceki bir imzanın kapsadığı bir baytı değiştirecek olursa, yazıcı bir belge üretmek yerine bir hata oluşturur. Bu, düzeltme zincirli iş akışları için imza bütünlüğünü korur. Hiçbir belge içeriği günlüğe alınmaz.

Uygunluk

Kaynak; artımlı güncelleme dil bilgisini ve Object Stream modelini ISO 32000-2’de ve düzeltme zincirleme gereksinimlerini ETSI EN 319 142-1 PAdES profilinde açıklar. RAG külliyatı yazım sırasında kullanılamadığından bu sayfa yalnızca kaynağın kendisinin bildirdiği kural başvurularını yineler ve hiçbir ek harici kural tanımlayıcısı belirtmez.

Enterprise sınır notu

Enterprise; davranış düzeyinde artımlı güncellemelerin üzerine kurulu daha üst katman imza yaşam döngüsü özellikleri (uzun vadeli doğrulama ve yenileme) ekler. Writer modülü yalnızca düzeltme ilkelini sağlar; bu daha üst katman özellikleri ayrıca belgelenir ve bir düzeltme yazmak için gerekli değildir.

Core yedeği / alternatifi

Pro olmadan NextPDF Core’un temel yazıcısını kullanın; yalnızca-ekleme kapısına sahip artımlı güncelleme düzeltmeleri ve Object Stream paketleme, Pro eklemeleridir. /modules/writer/ bölümüne bakın.

Yayımlama sınırı

Bu sayfa yalnızca dışarıdan gözlemlenebilen davranışı ve desteklenen genel API yüzeyini açıklar. İç ad alanı yolları, yardımcı sınıflar, mekanizma tabloları, runbook dosya adları ve bilet önekleri kapsam dışıdır.