Pro edisi

Projection

Sekilas pandang

Projection mengurai content stream PDF menjadi daftar token datar dan mengeluarkan content stream baru dari token-token tersebut. Pengeluaran memerlukan intent yang dideklarasikan secara eksplisit. Modul ini bukan editor PDF serbaguna.

Catatan. “Projection” di sini berarti projeksi token content-stream. Ini bukan projeksi koordinat atau geospasial. Untuk fitur geospasial, lihat modul Geo.

Ketersediaan & lisensi

Kapabilitas ini dikirimkan dalam NextPDF Pro (nextpdf/pro) dan diaktifkan dengan envelope lisensi tier Pro. Deployment tanpa entitlement tersebut tidak memuat kelas-kelas kapabilitas ini. Bandingkan edisi dan dapatkan lisensi.

Tidak ada flag lisensi per-fitur yang terpisah. Argumen ProjectionIntent yang diwajibkan menggerbang pengeluaran di tingkat API, bukan sebuah saklar lisensi.

Pemasangan

composer require nextpdf/pro:^3

Kode berada di bawah namespace NextPDF\Pro\Projection.

Tinjauan konseptual

ContentProjectionWriter menyediakan tiga operasi statis:

tokenize() mengurai content stream menjadi daftar token yang datar dan terurut. Ini hanya-baca dan tidak memerlukan intent.
emit() menulis content stream baru dari daftar token (yang mungkin telah dimodifikasi). Ia memerlukan sebuah ProjectionIntent.
roundTrip() melakukan tokenisasi lalu mengeluarkan ulang tanpa perubahan, untuk validasi.

Keluaran secara konseptual adalah content stream baru, bukan salinan yang diedit dari aslinya. Emitter menormalkan spasi dan komentar tetapi menjaga urutan operator dan nilai operand tetap persis. Enum intent memiliki tepat dua kasus — sanitasi (penyamaran) dan penyematan steganografis — dan secara sengaja tidak memiliki kasus generik, sehingga analisis statis dapat mendeteksi penggunaan yang tidak disengaja.

Mengapa ia bekerja seperti ini

Projection menolak menjadi editor PDF serbaguna. Pengeluaran membangun ulang content stream segar dari daftar token datar, sehingga aslinya tidak pernah dimutasi di tempat. Model satu-arah itulah yang membuat penyamaran dapat dipercaya: token yang dihapus tidak ada dalam keluaran, bukan sekadar ditutup cat. Karena itu emit() menuntut sebuah ProjectionIntent eksplisit, dan enum hanya menawarkan sanitasi dan penyematan steganografis — tanpa kasus generik. Analisis statis lalu dapat menandai setiap pengeluaran yang tidak memiliki tujuan yang dideklarasikan dan diketahui. Desain ini menukar kenyamanan pengeditan demi jaminan bahwa intent destruktif selalu terlihat di lokasi pemanggilan.

Latar desain: Redaction is not a black rectangle.

Kontrak perilaku

tokenize($contentStream) mengembalikan daftar token yang mencakup string, name, angka, array, dictionary, boolean, null, dan operator.
emit($tokens, $intent) memerlukan intent eksplisit; sistem tipe menegakkan ini di lokasi pemanggilan.
Keluaran roundTrip() tidak byte-identik dengan input, tetapi urutan operator dan nilai operand cocok.
Emitter memformat angka untuk menjaga perbedaan integer dan float serta meng-escape ulang string literal.
Dua intent yang dideklarasikan adalah sanitasi (operasi penyamaran yang destruktif dan tak-terbalikkan) dan penyematan steganografis.

Contoh kode — Mulai cepat

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

use NextPDF\Pro\Projection\ContentProjectionWriter;

$tokens = ContentProjectionWriter::tokenize($contentStream);

Contoh kode — Produksi

use NextPDF\Pro\Projection\ContentProjectionWriter;
use NextPDF\Pro\Projection\ProjectionIntent;

$tokens = ContentProjectionWriter::tokenize($contentStream);

// Validate first: a clean round-trip must hold before any modification.
$check = ContentProjectionWriter::roundTrip($contentStream);

// Apply your modification to $tokens, then emit with a declared intent.
$output = ContentProjectionWriter::emit($tokens, ProjectionIntent::Sanitization);

Kasus tepi & jebakan

Jalankan roundTrip() dan pastikan ia berhasil sebelum Anda memercayai sebuah urutan modifikasi-dan-pengeluaran. Perlakukan round-trip yang gagal sebagai kondisi berhenti.
Intent sanitasi bersifat tak-terbalikkan. Konten yang dihapus tidak dapat dipulihkan dari keluaran.
Emitter menormalkan spasi dan membuang komentar, sehingga perbandingan tingkat-byte dengan aslinya akan berbeda bahkan untuk round-trip yang tidak dimodifikasi.

Kinerja

Tokenisasi dan pengeluaran bersifat linear terhadap panjang content-stream. Tokenizer membatasi pembacaan escape oktal dan penanganan string heksa. Tidak ada angka throughput yang dipublikasikan. Ukur dengan content stream yang representatif.

Catatan keamanan

Argumen intent yang diwajibkan mencegah penyalahgunaan sebagai editor umum. Intent sanitasi bersifat destruktif dan tak-terbalikkan; verifikasi round-trip terlebih dahulu dan konfirmasikan keluaran yang disamarkan sebelum distribusi. Modul ini tidak mencatat konten apa pun.

Kesesuaian

Tokenisasi mengikuti konvensi leksikal dan content-stream dalam ISO 32000-2; sumber memberi anotasi pada klausa yang relevan. Korpus RAG tidak tersedia saat penulisan, sehingga halaman ini tidak menyatakan pengenal klausa eksternal apa pun dan membatasi pernyataan kesesuaian pada perilaku yang diverifikasi oleh tes modul.

Catatan batas Enterprise

Enterprise tidak mengubah perilaku Projection. Enterprise menambahkan fitur privasi dan kepatuhan tingkat lebih tinggi yang didokumentasikan secara terpisah; fitur tersebut tidak diperlukan untuk menggunakan API projection.

Fallback / alternatif Core

Tidak ada padanan Core. Tanpa Pro, pemanggil harus membangun tokenizer content-stream mereka sendiri; model projeksi tergerbang-intent adalah tambahan khusus-Pro.

Batas publikasi

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