Writer

Sekilas pandang

Modul Writer menambahkan revisi incremental-update ke sebuah PDF dan mengemas objek kecil ke dalam Object Stream. Incremental writer menegakkan aturan append-only: byte yang ada sebelum revisi tidak boleh berubah.

Ketersediaan & lisensi

Kapabilitas ini dikirimkan dalam NextPDF Pro (nextpdf/pro) dan diaktifkan dengan envelope lisensi tier Pro. Sebuah deployment tanpa entitlement tersebut tidak memuat kelas-kelas kapabilitas ini. Bandingkan edisi dan dapatkan lisensi. Tidak ada flag lisensi per-fitur yang terpisah; kodenya dikirimkan bersama edisi Pro.

Pemasangan

composer require nextpdf/pro:^3

Kodenya berada di bawah namespace NextPDF\Pro\Writer.

Tinjauan konseptual

Disediakan dua kapabilitas:

• IncrementalUpdateWriter menulis revisi baru. Ia menulis ulang katalog dengan entri yang digabung, menambahkan tabel referensi-silang tradisional untuk objek baru dan yang dimodifikasi, dan menulis trailer yang menautkan ke revisi sebelumnya. Ia menegakkan aturan append-only yang gagal-tertutup.
• ObjectStreamWriter mengelompokkan objek kecil ke dalam satu Object Stream terkompresi. Ini mengurangi ukuran tabel referensi-silang dan meningkatkan kompresi. Ia menolak objek yang akan melampaui ukuran stream maksimum dan menolak stream kosong.

Aturan append-only melindungi tanda tangan yang ada. Setiap byte yang dimiliki buffer sebelum revisi harus muncul tidak berubah pada posisi yang sama setelah revisi. Jika ada byte sebelumnya yang berubah, writer memunculkan galat dan tidak menghasilkan keluaran.

Mengapa ia bekerja seperti ini

Pilihan yang menjadi tumpuan adalah di mana gerbang append-only berada. Ia berada pada lingkup writer, bukan hanya di orkestrator tingkat-lebih-tinggi, sehingga setiap pemanggil sekarang dan masa depan mewarisi cakupan gagal-tertutup. Pemeriksaannya adalah uji kesamaan-prefiks murni: writer membuat snapshot prefiks buffer sebelum menambahkan, lalu memastikan setiap byte sebelumnya tidak berubah sesudahnya. Ini melindungi tanda tangan apa pun yang /ByteRange-nya mencakup prefiks tersebut, karena satu byte yang teralter akan diam-diam membatalkannya. Tabel referensi-silang tradisional dan pointer /Prev membawa revisi baru, karena incremental update harus menambahkan alih-alih menulis ulang. Biaya verifikasi bersifat linear terhadap prefiks yang ada, dan biaya itu diterima secara sengaja: integritas byte-yang-ditandatangani lebih diutamakan ketimbang salinan kedua.

Latar belakang desain: Incremental update dan mengapa itu penting.

Kontrak perilaku

• IncrementalUpdateWriter::writeRevision(...) mengembalikan offset byte tabel referensi-silang baru, sehingga Anda dapat merangkai revisi selanjutnya.
• Writer memverifikasi prefiks asli sama-byte sebelum dan sesudah penulisan. Sebuah divergensi memunculkan eksepsi writer yang membawa state pelanggaran-append-only.
• Revisi baru menggunakan tabel referensi-silang tradisional dan trailer dengan pointer /Prev; mencampur tabel dan stream lintas revisi diperbolehkan.
• ObjectStreamWriter::addObject() memunculkan galat overflow ketika menambahkan sebuah objek akan melampaui ukuran stream maksimum (65.536 byte tak-terkompresi untuk indeks ditambah body).
• ObjectStreamWriter::build() memunculkan galat ketika tidak ada objek yang ditambahkan; jika tidak, ia mengembalikan konten Object Stream terkompresi.

Contoh kode — Mulai cepat

Berikut mencerminkan API publik yang terdokumentasi. Repositori tidak mengirimkan contoh yang dapat dijalankan untuk modul ini.

use NextPDF\Pro\Writer\ObjectStreamWriter;

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

Contoh kode — Produksi

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.

Kasus tepi & jebakan

• Pemeriksaan append-only menyalin prefiks yang ada. Biayanya bertambah seiring ukuran dokumen yang sudah ditulis. Biaya ini disengaja dan melindungi byte yang ditandatangani.
• Batas ukuran Object Stream berada pada gabungan indeks dan body sebelum kompresi. Kelompokkan objek secara sesuai.
• Object Stream tidak boleh memuat tipe objek tertentu (misalnya, dictionary enkripsi). Tempatkan tipe tersebut sebagai objek tak-langsung yang langsung.

Performa

Verifikasi append-only bersifat linear terhadap ukuran prefiks dokumen yang ada. Pengemasan Object Stream mengurangi ukuran referensi-silang dan meningkatkan kompresi dengan biaya satu lintasan kompresi ekstra. Tidak ada angka throughput yang dipublikasikan. Ukur dengan dokumen yang representatif.

Catatan keamanan

Incremental writer bersifat gagal-tertutup. Jika sebuah jalur kode akan mengubah sebuah byte yang dicakup oleh tanda tangan sebelumnya, writer memunculkan galat alih-alih memproduksi dokumen. Ini melindungi integritas tanda tangan untuk alur kerja yang dirangkai-revisi. Tidak ada konten dokumen yang dicatat.

Kesesuaian

Sumbernya menganotasi tata bahasa incremental-update dan model Object Stream di ISO 32000-2 serta persyaratan perangkaian-revisi di profil PAdES ETSI EN 319 142-1. Karena korpus RAG tidak tersedia pada waktu penulisan, halaman ini hanya mengulang rujukan klausa yang dideklarasikan sumbernya sendiri dan tidak menyatakan pengenal klausa eksternal tambahan.

Catatan batas Enterprise

Enterprise menambahkan fitur siklus-hidup tanda tangan tingkat-lebih-tinggi (validasi jangka panjang dan pembaruan) yang dibangun di atas incremental update pada tingkat perilaku. Modul Writer hanya menyediakan primitif revisi; fitur tingkat-lebih-tinggi tersebut didokumentasikan secara terpisah dan tidak diperlukan untuk menulis sebuah revisi.

Fallback / alternatif Core

Tanpa Pro, gunakan writer dasar NextPDF Core; revisi incremental-update dengan gerbang append-only dan pengemasan Object Stream adalah tambahan Pro. Lihat /modules/writer/.

Batas publikasi

Halaman ini hanya mendokumentasikan perilaku yang dapat diamati dari luar dan permukaan API publik yang didukung. Jalur namespace internal, kelas helper, tabel mekanisme, nama berkas runbook, dan prefiks tiket berada di luar cakupan.

Lihat juga

• Writer — Referensi Mendalam
• Document
• Optimizer
• Output Pipeline