Document — Referensi Mendalam

Sekilas pandang

Modul Document menyediakan tiga primitif perakitan Pro: page-range splitting, merge multi-dokumen, dan konstruksi dictionary PDF Portfolio (Collection). PdfSplitter mengekstrak rentang halaman menjadi PDF mandiri yang konforman secara struktural dan menggabungkan seluruh dokumen menjadi satu berkas yang dinomori ulang. PdfPortfolio membangun Collection dictionary yang menampilkan berkas tertanam dengan kolom skema yang dapat diurutkan. Setiap entry point membatasi ukuran masukan dan jumlah objek terhadap masukan yang berbahaya.

Ketersediaan & lisensi

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

Permukaan API publik

Semua tipe modul berada di namespace NextPDF\Pro\Document. PageRange dan MergeResult adalah value object Core dari NextPDF\Document.

Simbol	Parameter	Perilaku bawaan	Mengembalikan	Melempar atau gagal dengan	Catatan
PdfSplitter::split()	string $pdfData, list<PageRange> $ranges, int $maxBytes = 100_000_000, int $maxRanges = 1000	Membangun satu segmen PDF mandiri per rentang	SplitResult	InvalidArgumentException pada header %PDF yang hilang; OverflowException pada penjaga ukuran, jumlah rentang, atau closure	Penjaga berjalan sebelum parsing apa pun
PdfSplitter::splitEvery()	string $pdfData, int $pagesPerSegment	Menurunkan rentang N-halaman yang kontigu; segmen terakhir boleh lebih pendek	SplitResult	InvalidArgumentException ketika $pagesPerSegment < 1 atau header hilang	Mendelegasikan ke split() dengan pagu bawaan
PdfSplitter::extractPages()	string $pdfData, PageRange $range	Mengembalikan satu rentang sebagai byte PDF mandiri	string	InvalidArgumentException pada header yang hilang; OverflowException pada penjaga closure	Tidak ada parameter pagu pada jalur ini
PdfSplitter::mergeDocuments()	list<string> $pdfs, int $maxInputs = 100, int $maxBytesEach = 100_000_000	Menggabungkan masukan secara berurutan menjadi satu PDF yang dinomori ulang	MergeResult	InvalidArgumentException pada daftar kosong atau masukan non-PDF; OverflowException pada penjaga jumlah, ukuran per-masukan, atau closure	Sejak 3.1.0; versi masukan tertinggi menentukan header keluaran
SplitResult	readonly $segments, $ranges, $totalPages	Membawa byte segmen mentah plus metadata sumber	—	—	Value object final readonly
SplitResult::count()	—	Menghitung segmen yang dihasilkan	int	—	—
SplitResult::segment()	int $index	Mengembalikan byte satu segmen	string	OutOfRangeException pada indeks di luar batas	Indeks berbasis nol
PdfPortfolio::__construct()	string $viewMode = 'tile'	Memvalidasi mode tampilan saat konstruksi	—	InvalidArgumentException pada mode selain tile, detail, hidden	—
PdfPortfolio::addSchema()	PortfolioField $field	Menambahkan satu kolom skema	self	—	Fluent
PdfPortfolio::addEntry()	PortfolioEntry $entry	Menambahkan satu entri berkas	self	—	Fluent
PdfPortfolio::getSchema()	—	Mengembalikan bidang skema yang terakumulasi	list<PortfolioField>	—	—
PdfPortfolio::getEntries()	—	Mengembalikan entri berkas yang terakumulasi	list<PortfolioEntry>	—	—
PdfPortfolio::count()	—	Menghitung entri berkas	int	—	—
PdfPortfolio::generateCollectionDictionary()	—	Mengemisi string Collection dictionary	string	—	Blok skema dan sort hanya muncul ketika ada bidang
PortfolioEntry	$filename, $data, $description = '', $mimeType = 'application/octet-stream', $customFields = []	Value object entri-berkas yang immutable	—	—	size() mengembalikan panjang byte data
PortfolioField	$name, PortfolioFieldType $type, $displayName = '', $order = 0, $visible = true	Value object kolom-skema yang immutable	—	—	effectiveDisplayName() jatuh kembali ke $name
PortfolioFieldType	Enum string: Text, Date, Number, FileName, Description, Size, ModDate, CreationDate	Memetakan setiap case ke /Subtype PDF melalui pdfSubtype()	string (S, D, N, F, Desc)	—	Case bertipe tanggal berbagi subtype D; case numerik berbagi N

Tanda tangan entry point:

public function split(string $pdfData, array $ranges, int $maxBytes = 100_000_000, int $maxRanges = 1000): SplitResult

public function mergeDocuments(
    array $pdfs,
    int $maxInputs = 100,
    int $maxBytesEach = 100_000_000,
): MergeResult

public function __construct(
    private readonly string $viewMode = 'tile',
)

public function generateCollectionDictionary(): string

Kontrak perilaku

Splitting dan merging berbagi satu pipeline object-graph:

• Masukan harus diawali dengan header %PDF. Penjaga ukuran dan jumlah berjalan sebelum parsing dan memunculkan OverflowException pada pelanggaran.
• Halaman daun dideteksi dengan memindai penanda objek-halaman; node pohon-halaman dikecualikan dari perhitungan.
• Parser mengindeks setiap objek indirect tak-terkompresi dengan pemindaian terminator yang sadar-stream. Kemunculan pertama dari sebuah id objek yang menang, sehingga override incremental-update tidak diterapkan.
• Atribut pohon-halaman yang dapat diwariskan (/Resources, /MediaBox, /CropBox, /Rotate) dimaterialisasi ke setiap halaman yang diekstrak dengan menelusuri rantai /Parent-nya, sehingga segmen bersifat mandiri.
• Closure referensi-indirect transitif setiap halaman dikumpulkan, mengecualikan back-edge /Parent, dan dinomori ulang ke dalam ruang id kontigu yang baru.
• Serializer mengemisi header, Catalog, pohon Pages, objek halaman, dan objek closure, lalu tabel cross-reference dengan offset yang akurat per byte dan sebuah startxref yang menunjuk ke kata kunci xref.
• mergeDocuments mengulang pipeline per masukan ke dalam satu ruang id bersama. Versi PDF masukan tertinggi menentukan header keluaran. Ini adalah pengganti yang konforman untuk Core merger yang dinonaktifkan, yang tetap fail-closed.
• Keluaran bersifat deterministik. Tidak ada timestamp atau pengidentifikasi acak yang diemisi, sehingga masukan identik menghasilkan byte identik.

Perakitan Portfolio:

• Konstruktor memvalidasi mode tampilan. Token /View yang diemisi adalah /T, /D, atau /H untuk tile, detail, dan hidden secara berurutan.
• generateCollectionDictionary() mengemisi /Type /Collection, token /View, blok /Schema ketika ada bidang, dan direktif /Sort pada bidang skema pertama, menaik.
• Setiap bidang skema mengemisi /Subtype (dari pdfSubtype()), /N (nama tampilan yang di-escape), /O (urutan), dan /V (visibilitas).
• Nama bidang disanitasi menjadi token nama PDF yang valid; karakter non-word menjadi underscore. Nilai string di-escape sebagai PDF literal string.
• Entri berkas diekspos melalui getEntries() untuk penyematan oleh lapisan penulisan. Collection dictionary itu sendiri hanya membawa view, schema, dan sort.

Kasus tepi & mode kegagalan

• Rentang yang tidak cocok dengan halaman mana pun menghasilkan segmen satu-halaman minimal (MediaBox 612 x 792), bukan galat.
• Dokumen tanpa penanda halaman yang dapat dideteksi dihitung sebagai satu halaman.
• Halaman yang disimpan di dalam object stream tidak dideteksi; hanya objek indirect tak-terkompresi yang berpartisipasi dalam ekstraksi.
• Ketika id objek duplikat ada, revisi dengan offset terendah yang digunakan; revisi incremental-update berikutnya diabaikan.
• Closure referensi per-segmen dibatasi pada 50.000 objek; graph yang secara jahat mereferensikan-diri atau fan-out memunculkan OverflowException.
• Pagu bawaan: masukan 100 MB, 1.000 rentang, 100 masukan merge. Semua dapat disetel pemanggil per panggilan.
• splitEvery() menolak ukuran segmen di bawah 1 dengan InvalidArgumentException.
• SplitResult::segment() menolak indeks di luar batas dengan OutOfRangeException.
• Dua nama bidang skema yang hanya berbeda pada tanda baca akan tersanitasi menjadi kunci dictionary yang sama; bidang yang belakangan secara diam-diam membayangi bidang yang lebih awal dalam skema yang diemisi.
• Modul ini tidak melakukan operasi kriptografis; mode FIPS tidak mengubah perilakunya.

Kesesuaian

Keluaran segmen dan merge mengikuti model objek-halaman dari ISO 32000-2; sumber menganotasi klausa yang relevan. Klaim yang dapat diperiksa secara eksternal:

• Tata letak trailer, offset byte startxref, dan terminator %%EOF mengikuti ISO 32000-2:2020, §7.5.5 — reference ef0f2a4b563b84f81b3e6428612bc47c510d94fc8096849d339abf0f3247d845.
• Nilai /View Collection dictionary (/T, /D, /H) mengikuti ISO 32000-2:2020, §12.3.5 — reference 5cefaaeb40f3ff98e3aba135ac57c9424a05c43144c1b9b5156bfd4295e08ddd.
• Entri /Subtype, /N, /O, dan /V bidang Collection mengikuti ISO 32000-2:2020, §12.3.5 (collection field dictionary) — reference 6300fbfdc8a913a8dc6f6ae34eff99f2bd03c4313a77777cdd5a8dd856d9537a.

Pernyataan ini mendeskripsikan kapabilitas yang diimplementasikan dan diverifikasi oleh tes modul. Dukungan untuk sebuah konstruk bukanlah klaim kesesuaian, dan kesesuaian bukanlah sertifikasi; NextPDF tidak memegang sertifikasi pihak ketiga untuk modul ini.

Catatan pengembangan

• Semua kelas modul bersifat final; tipe hasil dan value object bersifat readonly. Tipe splitter dan Portfolio berasal dari 1.9.0; mergeDocuments() ditambahkan pada 3.1.0.
• PageRange dan MergeResult adalah tipe Core, sehingga call site tetap portabel-antar-edisi.
• Trailer segmen hanya membawa /Size dan /Root; tidak ada pengidentifikasi berkas /ID atau dictionary /Info yang diemisi.
• Untuk alur incremental-update atau penandatanganan, serahkan byte segmen ke modul Writer alih-alih menyuntingnya di tempat.
• Modul ini tidak mencatat konten dokumen.

Batas publikasi

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

Lihat juga

• Document — Ikhtisar Kapabilitas
• Merge — Referensi Mendalam
• Writer — Referensi Mendalam
• Output Pipeline — Referensi Mendalam