Document — การอ้างอิงเชิงลึก

ภาพรวมโดยสังเขป

โมดูล Document มี primitive สำหรับการประกอบระดับ Pro สามอย่าง ได้แก่ การแยกช่วงหน้า การรวมหลายเอกสาร และการสร้าง PDF Portfolio (Collection) dictionary PdfSplitter สกัดช่วงหน้าออกมาเป็น PDF แบบสแตนด์อะโลนที่สอดคล้องเชิงโครงสร้าง และรวมทั้งเอกสารเข้าเป็นไฟล์เดียวที่เลขหน้าถูกกำหนดใหม่ PdfPortfolio สร้าง Collection dictionary ที่นำเสนอไฟล์ที่ฝังไว้ด้วยคอลัมน์สคีมาที่จัดเรียงได้ ทุกจุดเข้าใช้งานจำกัดขนาดอินพุตและจำนวนอ็อบเจกต์เพื่อป้องกันอินพุตที่มุ่งร้าย

ความพร้อมใช้งานและการอนุญาต

ความสามารถนี้มาพร้อมกับ NextPDF Pro (nextpdf/pro) และเปิดใช้งานด้วยซองใบอนุญาตระดับ Pro การนำไปใช้งานที่ไม่มีสิทธิ์ดังกล่าวจะไม่โหลดคลาสของความสามารถนี้ เปรียบเทียบรุ่นและขอใบอนุญาต

พื้นผิว API สาธารณะ

ชนิดทั้งหมดของโมดูลอยู่ในเนมสเปซ NextPDF\Pro\Document PageRange และ MergeResult เป็นอ็อบเจกต์ค่าของ Core จาก NextPDF\Document

สัญลักษณ์	พารามิเตอร์	พฤติกรรมปริยาย	คืนค่า	โยนหรือล้มเหลวด้วย	หมายเหตุ
PdfSplitter::split()	string $pdfData, list<PageRange> $ranges, int $maxBytes = 100_000_000, int $maxRanges = 1000	สร้างเซกเมนต์ PDF แบบสแตนด์อะโลนหนึ่งชิ้นต่อหนึ่งช่วง	SplitResult	InvalidArgumentException เมื่อไม่มีส่วนหัว %PDF; OverflowException เมื่อละเมิดการ์ดขนาด จำนวนช่วง หรือ closure	การ์ดทำงานก่อนการแยกวิเคราะห์ใด ๆ
PdfSplitter::splitEvery()	string $pdfData, int $pagesPerSegment	คำนวณช่วงแบบต่อเนื่องครั้งละ N หน้า เซกเมนต์สุดท้ายอาจสั้นกว่า	SplitResult	InvalidArgumentException เมื่อ $pagesPerSegment < 1 หรือไม่มีส่วนหัว	มอบหมายให้ split() ด้วยเพดานปริยาย
PdfSplitter::extractPages()	string $pdfData, PageRange $range	คืนค่าช่วงเดียวเป็นไบต์ PDF แบบสแตนด์อะโลน	string	InvalidArgumentException เมื่อไม่มีส่วนหัว; OverflowException เมื่อละเมิดการ์ด closure	เส้นทางนี้ไม่มีพารามิเตอร์เพดาน
PdfSplitter::mergeDocuments()	list<string> $pdfs, int $maxInputs = 100, int $maxBytesEach = 100_000_000	รวมอินพุตตามลำดับเป็น PDF ที่เลขหน้าถูกกำหนดใหม่หนึ่งไฟล์	MergeResult	InvalidArgumentException เมื่อลิสต์ว่างหรืออินพุตไม่ใช่ PDF; OverflowException เมื่อละเมิดการ์ดจำนวน ขนาดต่ออินพุต หรือ closure	ตั้งแต่ 3.1.0; เวอร์ชันอินพุตสูงสุดกำหนดส่วนหัวของเอาต์พุต
SplitResult	readonly $segments, $ranges, $totalPages	บรรจุไบต์เซกเมนต์ดิบพร้อมเมทาดาทาต้นทาง	—	—	อ็อบเจกต์ค่า final readonly
SplitResult::count()	—	นับเซกเมนต์ที่ผลิตได้	int	—	—
SplitResult::segment()	int $index	คืนค่าไบต์ของเซกเมนต์หนึ่งชิ้น	string	OutOfRangeException เมื่อดัชนีอยู่นอกช่วง	ดัชนีเริ่มจากศูนย์
PdfPortfolio::__construct()	string $viewMode = 'tile'	ตรวจสอบโหมดมุมมองขณะสร้าง	—	InvalidArgumentException เมื่อโหมดไม่ใช่ tile, detail, hidden	—
PdfPortfolio::addSchema()	PortfolioField $field	เพิ่มคอลัมน์สคีมา	self	—	แบบ fluent
PdfPortfolio::addEntry()	PortfolioEntry $entry	เพิ่มรายการไฟล์	self	—	แบบ fluent
PdfPortfolio::getSchema()	—	คืนค่าฟิลด์สคีมาที่สะสมไว้	list<PortfolioField>	—	—
PdfPortfolio::getEntries()	—	คืนค่ารายการไฟล์ที่สะสมไว้	list<PortfolioEntry>	—	—
PdfPortfolio::count()	—	นับรายการไฟล์	int	—	—
PdfPortfolio::generateCollectionDictionary()	—	ปล่อยสตริง Collection dictionary	string	—	บล็อกสคีมาและการจัดเรียงปรากฏเฉพาะเมื่อมีฟิลด์
PortfolioEntry	$filename, $data, $description = '', $mimeType = 'application/octet-stream', $customFields = []	อ็อบเจกต์ค่ารายการไฟล์ที่เปลี่ยนแปลงไม่ได้	—	—	size() คืนค่าความยาวไบต์ของข้อมูล
PortfolioField	$name, PortfolioFieldType $type, $displayName = '', $order = 0, $visible = true	อ็อบเจกต์ค่าคอลัมน์สคีมาที่เปลี่ยนแปลงไม่ได้	—	—	effectiveDisplayName() ย้อนกลับไปใช้ $name
PortfolioFieldType	อีนัมสตริง: Text, Date, Number, FileName, Description, Size, ModDate, CreationDate	แมปแต่ละเคสไปยัง PDF /Subtype ผ่าน pdfSubtype()	string (S, D, N, F, Desc)	—	เคสประเภทวันที่ใช้ subtype D ร่วมกัน; เคสตัวเลขใช้ N ร่วมกัน

ลายเซ็นของจุดเข้าใช้งาน:

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

ข้อกำหนดด้านพฤติกรรม

การแยกและการรวมใช้ไปป์ไลน์ object-graph เดียวกันร่วมกัน:

• อินพุตต้องขึ้นต้นด้วยส่วนหัว %PDF การ์ดขนาดและจำนวนทำงานก่อนการแยกวิเคราะห์และยก OverflowException เมื่อละเมิด
• หน้าใบ (leaf) ถูกตรวจหาโดยการสแกนหาเครื่องหมายอ็อบเจกต์หน้า; โหนดของ page-tree ถูกกันออกจากการนับ
• ตัวแยกวิเคราะห์ทำดัชนีอ็อบเจกต์ทางอ้อมที่ไม่ถูกบีบอัดทุกตัวด้วยการสแกนตัวสิ้นสุดที่รู้จักสตรีม การปรากฏครั้งแรกของ object id เป็นตัวชนะ ดังนั้นการแทนที่แบบ incremental-update จึงไม่ถูกนำมาใช้
• แอตทริบิวต์ของ page-tree ที่สืบทอดได้ (/Resources, /MediaBox, /CropBox, /Rotate) ถูกทำให้เป็นรูปธรรมบนแต่ละหน้าที่สกัดออกมาโดยการไล่ตามสาย /Parent ของหน้านั้น ดังนั้นเซกเมนต์จึงเป็นอิสระในตัวเอง
• closure ของการอ้างอิงทางอ้อมแบบ transitive ของแต่ละหน้าถูกรวบรวมไว้ โดยกัน back-edge ของ /Parent ออก และถูกกำหนดเลขใหม่ในปริภูมิ id ที่ต่อเนื่องกันใหม่
• ตัวซีเรียลไลซ์ปล่อยส่วนหัว, Catalog, ทรี Pages, อ็อบเจกต์หน้า และอ็อบเจกต์ closure จากนั้นเป็นตาราง cross-reference พร้อมออฟเซ็ตที่แม่นยำระดับไบต์ และ startxref ที่ชี้ไปยังคีย์เวิร์ด xref
• mergeDocuments ทำไปป์ไลน์ซ้ำต่ออินพุตแต่ละตัวลงในปริภูมิ id ที่ใช้ร่วมกันหนึ่งเดียว เวอร์ชัน PDF ของอินพุตที่สูงสุดกำหนดส่วนหัวของเอาต์พุต มันคือตัวแทนที่สอดคล้องมาตรฐานของตัวรวมของ Core ที่ถูกปิดใช้งาน ซึ่งยังคงล้มเหลวแบบปิด (fail-closed)
• เอาต์พุตเป็นแบบกำหนดได้แน่นอน ไม่มีการปล่อย timestamp หรือตัวระบุแบบสุ่ม ดังนั้นอินพุตที่เหมือนกันจึงให้ไบต์ที่เหมือนกัน

การประกอบ Portfolio:

• ตัวสร้างตรวจสอบโหมดมุมมอง โทเค็น /View ที่ปล่อยออกมาคือ /T, /D, หรือ /H สำหรับ tile, detail และ hidden ตามลำดับ
• generateCollectionDictionary() ปล่อย /Type /Collection, โทเค็น /View, บล็อก /Schema เมื่อมีฟิลด์ และคำสั่ง /Sort บนฟิลด์สคีมาแรกแบบเรียงจากน้อยไปมาก
• แต่ละฟิลด์สคีมาปล่อย /Subtype (จาก pdfSubtype()), /N (ชื่อแสดงผลที่ escape แล้ว), /O (ลำดับ) และ /V (การมองเห็น)
• ชื่อฟิลด์ถูกทำความสะอาดให้เป็นโทเค็นชื่อ PDF ที่ถูกต้อง; อักขระที่ไม่ใช่ตัวอักษรกลายเป็นขีดล่าง ค่าสตริงถูก escape เป็นสตริงลิเทอรัลของ PDF
• รายการไฟล์ถูกเปิดเผยผ่าน getEntries() เพื่อให้ชั้นการเขียนนำไปฝัง Collection dictionary เองบรรจุเพียงมุมมอง สคีมา และการจัดเรียงเท่านั้น

กรณีขอบและโหมดความล้มเหลว

• ช่วงที่ไม่ตรงกับหน้าใดเลยจะให้เซกเมนต์หน้าเดียวขั้นต่ำ (MediaBox 612 x 792) ไม่ใช่ข้อผิดพลาด
• เอกสารที่ไม่มีเครื่องหมายหน้าที่ตรวจพบได้จะถูกนับเป็นหนึ่งหน้า
• หน้าที่จัดเก็บภายใน object stream จะไม่ถูกตรวจพบ; มีเพียงอ็อบเจกต์ทางอ้อมที่ไม่ถูกบีบอัดเท่านั้นที่มีส่วนร่วมในการสกัด
• เมื่อมี object id ซ้ำกัน จะใช้ revision ที่ออฟเซ็ตต่ำที่สุด; revision แบบ incremental-update ที่มาทีหลังจะถูกละเว้น
• closure การอ้างอิงต่อเซกเมนต์ถูกจำกัดที่ 50,000 อ็อบเจกต์; กราฟที่อ้างอิงตัวเองหรือแตกแขนงอย่างมุ่งร้ายจะยก OverflowException
• เพดานปริยาย: อินพุต 100 MB, 1,000 ช่วง, อินพุตการรวม 100 ตัว ทั้งหมดผู้เรียกปรับได้ต่อการเรียกหนึ่งครั้ง
• splitEvery() ปฏิเสธขนาดเซกเมนต์ที่ต่ำกว่า 1 ด้วย InvalidArgumentException
• SplitResult::segment() ปฏิเสธดัชนีที่อยู่นอกช่วงด้วย OutOfRangeException
• ชื่อฟิลด์สคีมาสองชื่อที่ต่างกันเพียงเครื่องหมายวรรคตอนจะถูกทำความสะอาดเป็นคีย์ dictionary เดียวกัน; ฟิลด์ที่มาทีหลังจะบดบังฟิลด์ก่อนหน้าอย่างเงียบ ๆ ในสคีมาที่ปล่อยออกมา
• โมดูลนี้ไม่ทำการดำเนินการเข้ารหัสลับใด ๆ; โหมด FIPS ไม่เปลี่ยนแปลงพฤติกรรมของมัน

ความสอดคล้องกับมาตรฐาน

เอาต์พุตของเซกเมนต์และการรวมเป็นไปตามแบบจำลองอ็อบเจกต์หน้าของ ISO 32000-2; ต้นฉบับกำกับข้อกำหนดที่เกี่ยวข้องไว้ ข้อกล่าวอ้างที่ตรวจสอบได้จากภายนอก:

• เลย์เอาต์ trailer, ออฟเซ็ตไบต์ startxref และตัวสิ้นสุด %%EOF เป็นไปตาม ISO 32000-2:2020, §7.5.5 — reference ef0f2a4b563b84f81b3e6428612bc47c510d94fc8096849d339abf0f3247d845
• ค่า /View ของ Collection dictionary (/T, /D, /H) เป็นไปตาม ISO 32000-2:2020, §12.3.5 — reference 5cefaaeb40f3ff98e3aba135ac57c9424a05c43144c1b9b5156bfd4295e08ddd
• รายการ /Subtype, /N, /O และ /V ของฟิลด์ Collection เป็นไปตาม ISO 32000-2:2020, §12.3.5 (collection field dictionary) — reference 6300fbfdc8a913a8dc6f6ae34eff99f2bd03c4313a77777cdd5a8dd856d9537a

ข้อความเหล่านี้อธิบายความสามารถที่นำไปใช้จริงและตรวจสอบแล้วโดยการทดสอบของโมดูล การรองรับโครงสร้างหนึ่งไม่ใช่ข้อกล่าวอ้างความสอดคล้อง และความสอดคล้องไม่ใช่การรับรอง; NextPDF ไม่ถือการรับรองจากบุคคลที่สามสำหรับโมดูลนี้

บันทึกการพัฒนา

• คลาสทั้งหมดของโมดูลเป็น final; ชนิดผลลัพธ์และอ็อบเจกต์ค่าเป็น readonly ชนิดของ splitter และ Portfolio มีมาตั้งแต่ 1.9.0; mergeDocuments() ถูกเพิ่มใน 3.1.0
• PageRange และ MergeResult เป็นชนิดของ Core ดังนั้นจุดเรียกใช้จึงยังคงพกพาข้ามรุ่นได้
• trailer ของเซกเมนต์บรรจุเพียง /Size และ /Root เท่านั้น; ไม่มีการปล่อยตัวระบุไฟล์ /ID หรือ dictionary /Info
• สำหรับเวิร์กโฟลว์ incremental-update หรือการลงลายเซ็น ให้ส่งไบต์เซกเมนต์ไปยังโมดูล Writer แทนที่จะแก้ไขในที่ภายหลัง
• โมดูลนี้ไม่บันทึกเนื้อหาเอกสารลงล็อก

ขอบเขตการเผยแพร่

หน้านี้บันทึกเฉพาะพฤติกรรมที่สังเกตได้จากภายนอกและพื้นผิว API สาธารณะที่รองรับเท่านั้น เส้นทางเนมสเปซภายใน คลาสตัวช่วย ตารางกลไก ชื่อไฟล์ runbook และคำนำหน้าตั๋วอยู่นอกขอบเขต

ดูเพิ่มเติม

• Document — ภาพรวมความสามารถ
• Merge — การอ้างอิงเชิงลึก
• Writer — การอ้างอิงเชิงลึก
• Output Pipeline — การอ้างอิงเชิงลึก