Pro edisi

Document

Sekilas pandang

Modul Document memecah sebuah PDF menjadi segmen berdasarkan rentang halaman dan menyusun PDF Portfolio (Collection) dengan kolom skema yang dapat diurutkan. Kedua operasi dibatasi terhadap input yang bermusuhan.

Ketersediaan & lisensi

Kapabilitas ini dikirim dalam NextPDF Pro (nextpdf/pro) dan aktif dengan amplop lisensi tingkat-Pro. Sebuah deployment tanpa entitlement tersebut tidak memuat kelas-kelas kapabilitas ini. Document adalah bagian dari edisi Pro, tanpa penanda lisensi per-fitur terpisah. Bandingkan edisi dan dapatkan lisensi.

Pemasangan

composer require nextpdf/pro:^3

Kode berada di bawah namespace NextPDF\Pro\Document.

Tinjauan konseptual

Dua kapabilitas disediakan:

PdfSplitter mengekstrak rentang halaman menjadi segmen PDF yang mandiri. Ia mendeteksi halaman dengan memindai objek halaman dalam input mentah dan membungkus halaman terpilih dalam katalog dan page tree minimal. Ia mendukung pemecahan berbasis-rentang, pemecahan ukuran-tetap (splitEvery), dan ekstraksi rentang-tunggal (extractPages).
PdfPortfolio membangun dictionary PDF Collection yang mengagregasi lampiran berkas dengan skema yang terdefinisi. Ia mendukung mode tampilan tile, detail, dan hidden serta memancarkan dictionary yang sesuai untuk disertakan dalam katalog dokumen.

Mengapa ia bekerja seperti ini

Memecah sebuah PDF bukanlah pengirisan byte. Sebuah objek halaman merujuk sumber daya, font, dan content stream bersama melalui referensi tak-langsung. Ia juga mewarisi /MediaBox dan /Resources dari leluhur page-tree-nya. Maka splitter merekonstruksi setiap segmen sebagai graf objek yang mandiri: ia menelusuri penutupan referensi transitif dari halaman terpilih, mematerialkan atribut warisan, menomori ulang ke dalam ruang id yang baru, dan menulis tabel cross-reference dengan offset yang akurat-byte. Penelusuran penutupan dibatasi, karena graf fan-out yang bermusuhan jika tidak dapat menarik pekerjaan tak-terbatas ke dalam satu segmen. Hasilnya terbuka sebagai PDF mandiri yang valid, bukan fragmen dengan referensi menggantung.

Latar belakang desain: Anatomi sebuah berkas PDF.

Kontrak perilaku

PdfSplitter::split($pdfData, $ranges, $maxBytes = 100_000_000, $maxRanges = 1000) menegakkan batas ukuran-input dan batas jumlah-rentang, serta menolak input yang tidak diawali header PDF.
splitEvery($pdfData, $pagesPerSegment) menolak ukuran segmen di bawah 1; segmen terakhir dapat memuat lebih sedikit halaman.
PdfPortfolio menolak mode tampilan apa pun selain tile, detail, atau hidden pada saat konstruksi.
addSchema() dan addEntry() mengembalikan portfolio untuk fluent chaining; generateCollectionDictionary() mengembalikan string dictionary Collection.
Nama bidang skema disanitasi untuk dipakai sebagai objek nama PDF; nilai string di-escape untuk literal string PDF.

Contoh kode — Mulai cepat

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

use NextPDF\Pro\Document\PdfSplitter;
use NextPDF\Document\PageRange;

$result = (new PdfSplitter())->split($pdfBytes, [new PageRange(1, 5)]);

Contoh kode — Produksi

use NextPDF\Pro\Document\PdfSplitter;
use NextPDF\Document\PageRange;

$splitter = new PdfSplitter();

try {
    $result = $splitter->split(
        $pdfBytes,
        [new PageRange(1, 10), new PageRange(11, 20)],
        maxBytes: 50_000_000,
        maxRanges: 100,
    );
} catch (\InvalidArgumentException $e) {
    // Input rejected (not a PDF, or limits exceeded).
}

Kasus tepi & jebakan

Splitter merekonstruksi setiap segmen sebagai graf objek yang baru dengan tabel cross-reference yang nyata dan akurat-byte; segmen adalah PDF mandiri yang valid. Ia menomori ulang ke dalam ruang id yang baru alih-alih mempertahankan tata letak byte sumber, jadi serahkan byte segmen ke modul Writer untuk alur kerja incremental-update atau penandatanganan.
Rentang yang tidak cocok dengan halaman mana pun menghasilkan segmen satu-halaman minimal alih-alih sebuah error.
Pengurutan portfolio secara default mengikuti bidang skema pertama, menaik.

Performa

Pemecahan dan penyusunan portfolio bersifat linear terhadap ukuran input dan jumlah entri. Plafon input default adalah 100 MB dan plafon rentang default adalah 1000; keduanya dapat diturunkan oleh pemanggil. Ukur dengan dokumen representatif.

Catatan keamanan

Perlakukan input sebagai tidak tepercaya. Penjaga ukuran dan jumlah membatasi penggunaan sumber daya. Modul menyanitasi nama bidang dan meng-escape nilai string sebelum mencapai dictionary keluaran. Ia tidak mencatat konten dokumen.

Konformansi

Dictionary Portfolio mengikuti model PDF Collections dan splitter mengikuti model objek-halaman yang didefinisikan oleh ISO 32000-2; sumber menganotasi klausul yang relevan. Korpus RAG tidak tersedia pada saat penulisan, sehingga halaman ini tidak menegaskan pengidentifikasi klausul eksternal apa pun dan membatasi pernyataan konformansi pada perilaku yang diverifikasi oleh pengujian modul.

Catatan batas Enterprise

Enterprise tidak mengubah perilaku Document. Enterprise menambahkan fitur arsip dan kepatuhan tingkat-lebih-tinggi yang didokumentasikan terpisah; fitur tersebut tidak diwajibkan untuk pemecahan atau penyusunan Portfolio.

Fallback / alternatif Core

Tanpa Pro, gunakan primitif dokumen dasar NextPDF Core; pemecahan rentang-halaman dan penyusunan Portfolio adalah tambahan Pro. Lihat /modules/document/.

Batas publikasi

Halaman ini mendokumentasikan hanya 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.