Pro edisi

AST

Sekilas

Modul AST mengubah sebuah PDF menjadi pohon dokumen yang imutabel dan dapat dinavigasi. Ia menggunakan tagged-structure tree ketika ada dan fallback ke builder heuristik untuk dokumen untagged, melampirkan bounding box dan teks ke setiap node.

Ketersediaan & lisensi

Kapabilitas ini diapalkan dalam NextPDF Pro (nextpdf/pro) dan aktif dengan amplop 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. Kode diapalkan bersama edisi Pro; perilaku build sepenuhnya diatur oleh AstBuildOptions (batas resource dan rentang halaman), bukan oleh switch lisensi.

Pemasangan

composer require nextpdf/pro:^3

Kode tinggal di bawah namespace NextPDF\Pro\Ast.

Ikhtisar konseptual

AstBuilder mengorkestrasi pipeline PDF-ke-pohon: periksa cache, tolak input terenkripsi sejak awal, baca structure tree untuk PDF tagged, fallback ke jalur untagged jika tidak, lampirkan bounding box dari analisis content-stream, lalu cache hasilnya. Keluarannya adalah AstDocument yang node-nya imutabel; pembaruan merekonstruksi subtree yang terdampak secara bottom-up alih-alih memutasi di tempat.

Dua strategi fallback ada untuk PDF untagged: sebuah bare fallback dan builder heuristik opsional (AstBuildOptions::$useHeuristic). Modul juga menyediakan jalur emitter yang dapat menulis sebuah AST kembali ke PDF dan memverifikasi hasilnya, ditambah mutation log untuk melacak perubahan yang diterapkan pada pohon.

Mengapa ia bekerja seperti ini

Pohon bersifat imutabel secara konstruksi. Setiap suntingan membangun ulang hanya jalur root-ke-node yang terdampak dan berbagi subtree yang tak tersentuh berdasarkan identitas, sehingga sebuah AstDocument yang telah dibangun aman untuk dipegang, di-cache, dan diserahkan ke pembaca konkuren tanpa salinan defensif. Ini mencerminkan bagaimana PDF sendiri berubah di disk: jalur write-back menambahkan pembaruan inkremental melalui AstWriter alih-alih menulis ulang berkas, meninggalkan byte asli — dan tanda tangan apa pun yang sudah ada — tetap utuh. Sebuah revisi append-only juga murah untuk diverifikasi secara struktural, itulah sebabnya AstWriter dapat memeriksa keluarannya sendiri sebelum mengembalikannya. Merekonstruksi subtree alih-alih memutasi di tempat adalah satu keputusan yang membuat modul ini sekaligus dapat dinavigasi dan aman untuk disunting.

Latar belakang desain: Pembaruan inkremental dan mengapa ia penting.

Kontrak perilaku

AstBuilder::build($sourceHash) menerima hex SHA-256 penuh dari PDF sumber dan mengembalikan sebuah AstDocument.
PDF terenkripsi ditolak dengan error unsupported-encryption yang khusus; dekripsi sebelum membangun.
Ketika tidak ada structure tree, builder menggunakan jalur untagged secara otomatis — heuristik jika diaktifkan, bare fallback jika tidak.
Batas resource dalam AstBuildOptions (max node, max depth, max memory, timeout wall-clock) menyebabkan error build-limit atau build-timeout alih-alih pekerjaan tak terbatas.
Cache key memuat source hash dan options hash, sehingga dua build dengan input dan opsi yang identik mengembalikan pohon yang sama.
AstNode bersifat imutabel; konsumen menerima instance node baru ketika pohon berubah.

Contoh kode — Mulai cepat

Berikut mencerminkan API publik yang didokumentasikan. Repositori tidak mengapalkan contoh yang dapat dijalankan untuk modul ini.

use NextPDF\Pro\Ast\AstBuilder;
use NextPDF\Pro\Ast\AstBuildOptions;

$builder = new AstBuilder($pdfReader, new AstBuildOptions());
$document = $builder->build($sha256OfPdf);

Contoh kode — Produksi

use NextPDF\Pro\Ast\AstBuilder;
use NextPDF\Pro\Ast\AstBuildOptions;

$options = new AstBuildOptions(
    maxNodes: 100_000,
    maxDepth: 200,
    maxMemoryBytes: 256 * 1024 * 1024,
    timeoutSeconds: 30.0,
    useHeuristic: true,
);

$builder = new AstBuilder($pdfReader, $options, $astCache);

try {
    $document = $builder->build($sha256OfPdf);
} catch (\NextPDF\Pro\Ast\Exception\AstUnsupportedEncryptionException $e) {
    // Decrypt the source first, then retry.
}

Kasus tepi & jebakan

Halaman yang content stream-nya tidak dapat diuraikan dilewati selama pelampiran bounding-box; pohon tetap dikembalikan, hanya tanpa box untuk halaman tersebut.
Builder heuristik bersifat opt-in. Dengan ia dinonaktifkan, PDF untagged menghasilkan pohon yang lebih kasar dari bare fallback.
Rentang halaman dalam AstBuildOptions menggunakan indeks 0-based, inklusif; membiarkan kedua batas null memproses semua halaman.

Performa

Biaya build berskala dengan jumlah node dan jumlah halaman; AstBuildOptions membatasi keduanya. Cache memintas build berulang dari input yang sama dengan opsi yang sama. NextPDF tidak menerbitkan timing per-dokumen tetap di sini; timeout wall-clock (default 30 s) dan plafon node (default 100.000) membatasi pekerjaan worst-case. Ukur dengan dokumen representatif.

Catatan keamanan

Perlakukan input sebagai tidak tepercaya. Builder menolak PDF terenkripsi alih-alih memproses sebagian. Plafon resource (node, depth, memory, time) melindungi dari dokumen patologis atau hostil. Modul ini tidak mencatat konten dokumen.

Konformansi

Jalur structure-tree membaca struktur tagged-PDF yang didefinisikan oleh ISO 32000-2; sumber modul menganotasi klausa content-stream dan struktur yang relevan. Karena korpus RAG tidak tersedia saat penulisan, halaman ini tidak menegaskan pengenal klausa eksternal dan membatasi pernyataan konformansi pada perilaku yang diverifikasi oleh test modul.

Catatan batas Enterprise

Enterprise tidak mengubah perilaku AST. Enterprise menambahkan kapabilitas kepatuhan dan archival tier-lebih-tinggi yang didokumentasikan secara terpisah; itu tidak diperlukan untuk membangun atau mengonsumsi sebuah AST.

Fallback / alternatif Core

Tanpa Pro, tidak ada pohon dokumen yang setara; pemanggil mengurai content stream secara langsung menggunakan primitif NextPDF Core. Lihat /modules/ast/.

Batas publikasi

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