Pro รุ่น

เอกสาร

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

โมดูล Document แยก PDF ออกเป็นส่วน ๆ ตามช่วงหน้า และประกอบ PDF Portfolio (Collection) พร้อมคอลัมน์ schema ที่จัดเรียงได้ ทั้งสองการทำงานถูกจำกัดขอบเขตเพื่อรับมืออินพุตที่เป็นปฏิปักษ์

การมีให้ใช้และการอนุญาต

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

การติดตั้ง

composer require nextpdf/pro:^3

โค้ดอยู่ภายใต้เนมสเปซ NextPDF\Pro\Document

ภาพรวมเชิงแนวคิด

มีสองความสามารถให้ใช้:

PdfSplitter สกัดช่วงหน้าออกเป็นส่วน PDF ที่ยืนได้ด้วยตัวเอง โดยตรวจจับหน้าด้วยการสแกนหาออบเจ็กต์หน้าในอินพุตดิบ และห่อหุ้มหน้าที่เลือกไว้ในแคทาลอกและ page tree ขั้นต่ำ รองรับการแยกตามช่วง การแยกตามขนาดตายตัว (splitEvery) และการสกัดช่วงเดียว (extractPages)
PdfPortfolio สร้างพจนานุกรม PDF Collection ที่รวมสิ่งแนบไฟล์เข้าด้วยกันตาม schema ที่กำหนดไว้ รองรับโหมดมุมมองแบบ tile, detail และ hidden และปล่อยพจนานุกรมที่เหมาะสำหรับรวมไว้ในแคทาลอกเอกสาร

เหตุใดจึงทำงานเช่นนี้

การแยก PDF ไม่ใช่การตัดเป็นชิ้นไบต์ ออบเจ็กต์หน้าอ้างอิงถึงทรัพยากรร่วม ฟอนต์ และสตรีมเนื้อหาด้วยการอ้างอิงทางอ้อม อีกทั้งยังสืบทอด /MediaBox และ /Resources จากบรรพบุรุษใน page tree ดังนั้นตัวแยกจึงสร้างแต่ละส่วนขึ้นใหม่ให้เป็นกราฟออบเจ็กต์ที่สมบูรณ์ในตัวเอง โดยเดินสำรวจ closure ของการอ้างอิงแบบทรานซิทีฟของหน้าที่เลือก ทำให้แอตทริบิวต์ที่สืบทอดมาเป็นรูปธรรม กำหนดหมายเลขใหม่ในพื้นที่ id ใหม่ และเขียนตาราง cross-reference พร้อมออฟเซ็ตที่เที่ยงตรงระดับไบต์ การเดินสำรวจ closure ถูกจำกัดขอบเขต เพราะกราฟที่แตกแขนงแบบปฏิปักษ์อาจดึงงานไม่จำกัดเข้าสู่ส่วนเดียวได้ ผลลัพธ์เปิดได้เป็น PDF ที่ยืนได้ด้วยตัวเองอย่างถูกต้อง ไม่ใช่ชิ้นส่วนที่มีการอ้างอิงค้างคา

ภูมิหลังการออกแบบ: กายวิภาคของไฟล์ PDF

สัญญาพฤติกรรม

PdfSplitter::split($pdfData, $ranges, $maxBytes = 100_000_000, $maxRanges = 1000) บังคับใช้ขีดจำกัดขนาดอินพุตและขีดจำกัดจำนวนช่วง และปฏิเสธอินพุตที่ไม่ขึ้นต้นด้วยส่วนหัว PDF
splitEvery($pdfData, $pagesPerSegment) ปฏิเสธขนาดส่วนที่ต่ำกว่า 1 ส่วนสุดท้ายอาจมีหน้าน้อยกว่า
PdfPortfolio ปฏิเสธโหมดมุมมองใด ๆ นอกเหนือจาก tile, detail หรือ hidden ณ เวลาสร้างออบเจ็กต์
addSchema() และ addEntry() คืนค่า portfolio เพื่อการต่อสายแบบ fluent generateCollectionDictionary() คืนค่าสตริงพจนานุกรม Collection
ชื่อฟิลด์ schema ถูกทำให้ปลอดภัยสำหรับใช้เป็นออบเจ็กต์ชื่อ PDF ค่าสตริงถูกหลีกอักขระสำหรับสตริง literal ของ PDF

ตัวอย่างโค้ด — เริ่มต้นอย่างรวดเร็ว

โค้ดต่อไปนี้สะท้อน API สาธารณะที่บันทึกไว้ คลังเก็บไม่ได้แนบตัวอย่างที่รันได้สำหรับโมดูลนี้

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

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

ตัวอย่างโค้ด — การใช้งานจริง

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).
}

กรณีขอบและข้อควรระวัง

ตัวแยกสร้างแต่ละส่วนขึ้นใหม่เป็นกราฟออบเจ็กต์ใหม่พร้อมตาราง cross-reference ที่แท้จริงและเที่ยงตรงระดับไบต์ ส่วนต่าง ๆ เป็น PDF ที่ยืนได้ด้วยตัวเองอย่างถูกต้อง มันกำหนดหมายเลขใหม่ในพื้นที่ id ใหม่แทนที่จะรักษาเลย์เอาต์ไบต์ต้นฉบับ ดังนั้นจงส่งไบต์ของส่วนให้โมดูล Writer สำหรับเวิร์กโฟลว์การอัปเดตแบบเพิ่มหน่วยหรือการลงลายเซ็น
ช่วงที่ไม่ตรงกับหน้าใดเลยจะให้ส่วนขั้นต่ำหนึ่งหน้าแทนที่จะเป็นข้อผิดพลาด
การจัดเรียง Portfolio ตั้งค่าเริ่มต้นเป็นฟิลด์ schema แรก จากน้อยไปมาก

ประสิทธิภาพ

การแยกและการประกอบ portfolio เป็นเชิงเส้นตามขนาดอินพุตและจำนวนรายการ เพดานอินพุตเริ่มต้นคือ 100 MB และเพดานช่วงเริ่มต้นคือ 1000 ทั้งคู่ผู้เรียกปรับลดลงได้ จงวัดด้วยเอกสารที่เป็นตัวแทน

บันทึกด้านความปลอดภัย

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

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

พจนานุกรม Portfolio เป็นไปตามแบบจำลอง PDF Collections และตัวแยกเป็นไปตามแบบจำลองออบเจ็กต์หน้าที่กำหนดโดย ISO 32000-2 ต้นฉบับอธิบายข้อกำหนดที่เกี่ยวข้องไว้ คอร์ปัส RAG ไม่พร้อมใช้งาน ณ เวลาเขียน ดังนั้นหน้านี้จึงไม่ยืนยันตัวระบุข้อกำหนดภายนอกใด ๆ และจำกัดข้อความความสอดคล้องไว้เฉพาะพฤติกรรมที่ตรวจสอบโดยการทดสอบของโมดูล

บันทึกขอบเขตของ Enterprise

Enterprise ไม่เปลี่ยนพฤติกรรมของ Document Enterprise เพิ่มฟีเจอร์การจัดเก็บถาวรและการปฏิบัติตามข้อกำหนดระดับสูงขึ้นที่บันทึกแยกต่างหาก โดยไม่จำเป็นสำหรับการแยกหรือการประกอบ Portfolio

ทางสำรอง / ทางเลือกของ Core

หากไม่มี Pro ให้ใช้พรีมิทิฟเอกสารพื้นฐานของ NextPDF Core การแยกตามช่วงหน้าและการประกอบ Portfolio เป็นการเพิ่มเติมของ Pro ดู /modules/document/

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

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