Writer — Derinlemesine başvuru

Bir bakışta

Writer modülü, PDF artımlı güncelleme düzeltmeleri yazar ve küçük nesneleri Object Stream’lere paketler. Artımlı yazıcı, fail-closed bir yalnızca-ekleme kuralını zorunlu kılar: bir düzeltmeden önce arabelleğin tuttuğu her bayt, düzeltmeden sonra değişmeden kalmalıdır. Object Stream oluşturucu, uygun nesneleri sınırlı bir boyut altında tek bir FlateDecode ile sıkıştırılmış /Type /ObjStm nesnesinde gruplar.

Kullanılabilirlik ve lisanslama

Bu yetenek NextPDF Pro (nextpdf/pro) ile 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 lisans edinin. Özellik başına bir lisans bayrağı yoktur; kod, Pro sürümüyle birlikte gelir.

Genel API yüzeyi

Modül, NextPDF\Pro\Writer ad alanı altında yer alır. Tüm genel semboller aşağıda listelenmiştir. Değer nesneleri, değişmez final readonly sınıflarıdır.

Sembol	Parametreler	Varsayılan davranış	Döndürür	Fırlatır veya şununla başarısız olur	Notlar
IncrementalUpdateWriter::writeRevision	BinaryBuffer $buffer, ObjectRegistry $registry, int $prevXrefOffset, int $catalogObject, array $catalogEntries, array $catalogUpdates, array $newObjectNumbers, string $fileId	Statik. Kataloğu birleştirilmiş girdilerle yeniden yazar, yeni ve değiştirilmiş nesneler için geleneksel bir çapraz başvuru tablosu ekler ve /Size, /Root, /Prev ile /ID içeren bir fragman yazar. Düzeltme öncesi önekin daha sonra bayt-eşit olduğunu doğrular.	int — yeni çapraz başvuru tablosunun bayt ofseti	Yalnızca-ekleme önek denetimi başarısız olduğunda \NextPDF\Exception\WriterException; getWriterState(), dss-append-only-invariant döndürür	Statik giriş noktası. İhlalde kullanılabilir çıktı yoktur.
ObjectStreamWriter::addObject	int $objectNumber, string $content	Bir boyut denetiminin ardından bekleyen akışa bir nesne ekler.	void	Birleştirilmiş dizin artı gövde 65.536 baytı aşacak olduğunda OverflowException	$content, N 0 obj / endobj sarmalayıcılarını dışlar.
ObjectStreamWriter::canAccept	string $content	Dizin ek yükünü tahmin eder ve çalışan toplamı maksimuma karşı sınar.	bool	Fırlatmaz	Saf yüklem; durum değişikliği yoktur.
ObjectStreamWriter::build	yok	Dizini oluşturur, gövdeleri birleştirir, FlateDecode ile sıkıştırır ve /Type /ObjStm sözlüğünü sarmalar.	string — ham Object Stream içeriği	Hiçbir nesne eklenmediğinde veya bir zlib sıkıştırma hatasında ObjectStreamWriteException	Çağıran, nesne numarasını atar ve işaretçileri sarmalar.
ObjectStreamWriter::getEntries	yok	Biriktirilen nesneler için gövdeye göreli ofsetleri yeniden hesaplar.	list<ObjectStreamEntry>	Fırlatmaz	Ofsetler, gövde bölümüne görelidir.
ObjectStreamWriter::count	yok	Biriktirilen nesnelerin sayısını bildirir.	int	Fırlatmaz	—
ObjStmCompressor::__construct	int $maxStreamSize = 65536, int $maxObjectsPerStream = 200	Gruplama için kullanılan boyut ve nesne sayısı sınırlarını saklar.	—	Fırlatmaz	Varsayılanlar, modülün Object Stream ayarıyla eşleşir.
ObjStmCompressor::groupObjects	list<array{number: int, generation?: int, content: string}> $objects	Uygun olmayan nesneleri süzer, ardından geri kalanı boyut ve sayı sınırları içindeki yazıcılara paketler.	list<ObjectStreamWriter>	Fırlatmaz; uygun olmayan nesneler atlanır	Sıfır olmayan üretim numaralı nesneler, normal serileştirmeye düşer.
ObjStmCompressor::isEligible	string $content, int $generation = 0	Akış nesnelerini, /Encrypt, /XRef, /Catalog ve sıfır olmayan herhangi bir üretimi reddeder.	bool	Fırlatmaz	/Type eşleştirmesi, boşluk ve #xx kaçış toleranslıdır.
ObjStmCompressor::writeToBuffer	list<ObjectStreamWriter> $streams, BinaryBuffer $buffer, ObjectRegistry $registry	Akış başına bir taşıyıcı nesne ayırır, type-2 sıkıştırılmış girdileri kaydeder ve her ObjStm bloğunu yazar.	list<int> — taşıyıcı nesne numaraları	Nadir bir sıkıştırma hatasında build()’den gelen ObjectStreamWriteException’ı yayar	Uygun olmayan nesneler yazıldıktan sonra ve çapraz başvuru yayılmadan önce çalıştırın.
ObjStmCompressor::estimateSavings	list<ObjectStreamWriter> $streams, int $originalSize	Sıkıştırılmış boyutu orijinale karşı ölçmek için her akışı oluşturur.	ObjStmCompressionResult	Nadir bir sıkıştırma hatasında build()’den gelen ObjectStreamWriteException’ı yayar	Salt-okunur ölçüm yardımcısı.
ObjectStreamEntry::__construct	int $objectNumber, string $content, int $offset	Paketlenmiş bir nesnenin ve gövde ofsetinin değişmez kaydı.	—	Fırlatmaz	final readonly; genel özellikler.
ObjStmCompressionResult::__construct	int $originalObjectCount, int $streamCount, int $estimatedOriginalSize, int $estimatedCompressedSize	Değişmez metrik kabı.	—	Fırlatmaz	final readonly; genel özellikler.
ObjStmCompressionResult::savedBytes	yok	Orijinal eksi sıkıştırılmış boyutu döndürür.	int	Fırlatmaz	Paketleme veriyi genişlettiğinde negatif olabilir.
ObjStmCompressionResult::savedPercent	yok	Yüzde azalmayı döndürür.	float	Fırlatmaz	Orijinal boyut sıfır olduğunda 0.0 döndürür.
ObjStmCompressionResult::compressionRatio	yok	Sıkıştırılmış boyutu orijinale bölerek döndürür.	float	Fırlatmaz	Orijinal boyut sıfır olduğunda 1.0 döndürür.
ObjectStreamWriteException	—	Bir Object Stream oluşturma hatasını bildirir.	—	RuntimeException’ı genişletir	build() tarafından fırlatılır; geriye dönük uyumluluk için RuntimeException üzerinden yakalanabilir.

Giriş noktası imzaları

final class IncrementalUpdateWriter
{
    public static function writeRevision(
        BinaryBuffer $buffer,
        ObjectRegistry $registry,
        int $prevXrefOffset,
        int $catalogObject,
        array $catalogEntries,
        array $catalogUpdates,
        array $newObjectNumbers,
        string $fileId,
    ): int;
}

final class ObjectStreamWriter
{
    public function addObject(int $objectNumber, string $content): void;
    public function canAccept(string $content): bool;
    public function build(): string;
    /** @return list<ObjectStreamEntry> */
    public function getEntries(): array;
    public function count(): int;
}

final class ObjStmCompressor
{
    public function __construct(
        int $maxStreamSize = 65536,
        int $maxObjectsPerStream = 200,
    );

    /**
     * @param list<array{number: int, generation?: int, content: string}> $objects
     * @return list<ObjectStreamWriter>
     */
    public function groupObjects(array $objects): array;

    public function isEligible(string $content, int $generation = 0): bool;

    /**
     * @param list<ObjectStreamWriter> $streams
     * @return list<int>
     */
    public function writeToBuffer(array $streams, BinaryBuffer $buffer, ObjectRegistry $registry): array;

    /** @param list<ObjectStreamWriter> $streams */
    public function estimateSavings(array $streams, int $originalSize): ObjStmCompressionResult;
}

Davranış sözleşmesi

writeRevision, bir artımlı güncelleme düzeltmesi yazar. Yazmadan önce mevcut arabellek önekinin anlık görüntüsünü alır. Kataloğu birleştirilmiş girdilerle yeniden yazar, yeni nesne ofsetlerini kaydeder, bitişik alt bölümler hâlinde gruplandırılmış geleneksel bir çapraz başvuru tablosu yazar ve /Size, /Root, /Prev ile /ID içeren bir fragman yazar. Yazdıktan sonra öneki yeniden karşılaştırır. Daha önceki herhangi bir bayt değiştiyse, yalnızca-ekleme-ihlali durumunu taşıyan WriterException fırlatır ve kullanılabilir bir çıktı döndürmez. Başarı durumunda, başka düzeltmeleri zincirlemek için yeni çapraz başvuru tablosunun bayt ofsetini döndürür. Düzeltmeler arasında çapraz başvuru tablolarının ve akışlarının karıştırılmasına izin verilir.

ObjectStreamWriter, nesneleri biriktirir. addObject, birleştirilmiş dizin ve gövde, maksimum 65.536 bayt (sıkıştırılmamış) değerini aşacak olduğunda bir taşma hatası fırlatır. build, boş bir akışta bir hata fırlatır; aksi hâlde dizin ile gövdeyi sıkıştırır ve /Type /ObjStm, /N, /First, /Length ve /Filter /FlateDecode girdileriyle Object Stream içeriğini döndürür. Çağıran, nesne numarasını atar ve N 0 obj / endobj işaretçilerini sarmalar.

ObjStmCompressor, hangi nesnelerin paketleneceğine karar verir. Akış nesnelerini, şifreleme sözlüklerini, çapraz başvuru akışlarını, belge kataloğunu ve sıfır olmayan üretim numaralı herhangi bir nesneyi dışlar. writeToBuffer, akış başına bir taşıyıcı nesne ayırır, paketlenmiş her nesneyi bir type-2 sıkıştırılmış çapraz başvuru girdisi olarak kaydeder ve ObjStm bloğunu geçerli arabellek ofsetinde yazar. estimateSavings, arabelleği değiştirmeden boyut metriklerini hesaplamak için her akışı oluşturur.

Uç durumlar ve başarısızlık modları

• Yalnızca-ekleme denetimi mevcut öneki kopyalar. Maliyeti, zaten yazılmış belgenin boyutuyla artar. Bu maliyet kasıtlıdır ve imzalı baytları korur.
• Object Stream sınırı, sıkıştırılmamış dizin artı gövdeye uygulanır. Şifreleme sözlüğünü ve diğer dışlanan nesne türlerini doğrudan dolaylı nesneler olarak yerleştirin.
• /Type dışlaması, keyfi belirteç arası boşluğa ve #xx onaltılık kaçışa toleranslıdır. /Type /Encrypt, /Type\n/Encrypt ve /Type /#45ncrypt gibi biçimlerin tümü reddedilir, yalnızca kanonik değişmez yazım değil.
• Sıfır olmayan üretim numarası taşıyan herhangi bir nesne, uygun olmayan olarak değerlendirilir ve normal N G obj … endobj serileştirmesine düşer; çünkü sıkıştırılmış bir nesnenin üretimi örtük olarak sıfırdır.
• writeToBuffer, uygun olmayan tüm nesneler yazıldıktan sonra ve çapraz başvuru yayılmadan önce çalıştırılmalıdır. Paketlenmiş nesneler ayrıca ayrı olarak serileştirilmemelidir.

FIPS modu davranışı

Writer modülü hiçbir kriptografik işlem gerçekleştirmez. Daha önceki bir bayt değişecek olduğunda yaymayı reddederek imzalı baytları korur; bu, kriptografik bir test değil, bir bayt-eşitlik testidir. İmzalama ve karma için FIPS algoritma seçimi, bu yazıcı tarafından değil, imzalama modülü tarafından yönetilir. FIPS modunu etkinleştirmek veya devre dışı bırakmak, herhangi bir Writer yönteminin davranışını değiştirmez.

Uyumluluk

NextPDF, modülü ISO 32000-2:2020’ye karşı uygular. Artımlı yazıcı, §7.5.6 artımlı güncelleme dil bilgisini izler: her düzeltme, yalnızca yeni, değişmiş veya silinmiş nesneleri kapsayan bir çapraz başvuru bölümü ve /Prev girdisi önceki çapraz başvurunun ofsetini veren bir fragman ekler. Object Stream oluşturucu, §7.5.7 object-stream modelini izler: /First girdisinden itibaren ölçülen artan sırada ofsetlerle, nesne numarası ve ofset çiftlerinden oluşan bir dizin, paketlenmiş nesne gövdelerinden önce gelir. Her iki kural başvurusu da ISO 32000-2:2020 külliyatına karşı doğrulandı. PAdES B-LT ve B-LTA iş akışları için düzeltme zincirleme, kaynakta not edildiği gibi ETSI EN 319 142-1 §5.4’ü izler. Bir kural için destek, bir mühendislik yetenek beyanıdır, bir sertifikasyon değildir; NextPDF hiçbir resmi uyumluluk sertifikasyonu tutmaz.

Geliştirme notları

• Paketi composer require nextpdf/pro:^3 ile yükleyin. Sınıflar, NextPDF\Pro\Writer altında çözümlenir.
• IncrementalUpdateWriter::writeRevision, statik bir giriş noktasıdır; düzeltmeler arasında hiçbir örnek durumu tutmaz.
• ObjectStreamEntry, ObjStmCompressionResult, IncrementalUpdateWriter ve sıkıştırıcı birlikte modülün genel yüzeyini oluşturur; depo, bunun için çalıştırılabilir bir örnek içermez.
• writeRevision’dan gelen bir WriterException, bir yalnızca-ekleme ihlalini gösterir. Bunu kesin bir başarısızlık olarak değerlendirin ve arabelleği atın.
• Object Stream taşıyıcıları dolaylı nesnelerdir; çağıran, nesne numaralarını kayıt defteri aracılığıyla atar.

Yayın sınırı

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

Ayrıca bkz.

• Writer
• Document — Derinlemesine başvuru
• Optimizer — Derinlemesine başvuru