AST

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

โมดูล AST เปลี่ยน PDF ให้เป็นต้นไม้เอกสารที่ไม่เปลี่ยนแปลงและนำทางได้ โดยใช้ tagged-structure tree เมื่อมี และถอยกลับไปใช้ตัวสร้างแบบ heuristic สำหรับเอกสารที่ไม่ติดแท็ก พร้อมแนบ bounding box และข้อความให้กับแต่ละ node

ความพร้อมใช้งานและสิทธิ์การใช้งาน

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

ไม่มีแฟล็กสิทธิ์การใช้งานต่อฟีเจอร์ โค้ดมาพร้อมรุ่น Pro พฤติกรรมการสร้างถูกควบคุมทั้งหมดโดย AstBuildOptions (ขีดจำกัดทรัพยากรและช่วงหน้า) ไม่ใช่โดยสวิตช์สิทธิ์การใช้งาน

การติดตั้ง

composer require nextpdf/pro:^3

โค้ดอยู่ภายใต้ namespace NextPDF\Pro\Ast

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

AstBuilder ประสานงานไปป์ไลน์ PDF-เป็น-tree คือ ตรวจสอบแคช, ปฏิเสธอินพุตที่เข้ารหัสตั้งแต่เนิ่น ๆ, อ่าน structure tree สำหรับ PDF ที่ติดแท็ก, ถอยกลับไปใช้เส้นทางที่ไม่ติดแท็กในกรณีอื่น, แนบ bounding box จากการวิเคราะห์ content stream แล้วแคชผลลัพธ์ เอาต์พุตคือ AstDocument ที่ node ของมันไม่เปลี่ยนแปลง การอัปเดตจะสร้าง subtree ที่ได้รับผลกระทบขึ้นใหม่จากล่างขึ้นบนแทนที่จะแก้ไขในที่

มีกลยุทธ์ fallback สองแบบสำหรับ PDF ที่ไม่ติดแท็ก คือ bare fallback และตัวสร้างแบบ heuristic ที่ไม่บังคับ (AstBuildOptions::$useHeuristic) โมดูลยังมีเส้นทาง emitter ที่สามารถเขียน AST กลับไปยัง PDF และตรวจสอบผลลัพธ์ บวกกับ mutation log สำหรับติดตามการเปลี่ยนแปลงที่ใช้กับ tree

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

tree ไม่เปลี่ยนแปลงโดยการออกแบบ การแก้ไขแต่ละครั้งจะสร้างเฉพาะเส้นทางจาก root ถึง node ที่ได้รับผลกระทบขึ้นใหม่ และแบ่งปัน subtree ที่ไม่ถูกแตะต้องด้วย identity ดังนั้น AstDocument ที่สร้างแล้วจึงปลอดภัยที่จะถือ, แคช และส่งต่อให้ผู้อ่านพร้อมกันโดยไม่ต้องทำ defensive copy สิ่งนี้สะท้อนวิธีที่ PDF เองเปลี่ยนแปลงบนดิสก์ คือ เส้นทาง write-back เพิ่ม incremental update ผ่าน AstWriter แทนที่จะเขียนไฟล์ใหม่ ทำให้ไบต์เดิม — และลายเซ็นที่มีอยู่ — ยังคงสภาพเดิม revision แบบ append-only ยังตรวจสอบเชิงโครงสร้างได้ง่าย จึงเป็นเหตุผลที่ AstWriter สามารถตรวจสอบเอาต์พุตของตนเองก่อนคืนค่าได้ การสร้าง subtree ขึ้นใหม่แทนที่จะแก้ไขในที่คือการตัดสินใจเดียวที่ทำให้โมดูลทั้งนำทางได้และแก้ไขได้อย่างปลอดภัย

ที่มาของการออกแบบ Incremental update และเหตุใดจึงสำคัญ

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

• AstBuilder::build($sourceHash) รับ SHA-256 hex เต็มของ PDF ต้นทางและคืนค่า AstDocument
• PDF ที่เข้ารหัสจะถูกปฏิเสธด้วยข้อผิดพลาด unsupported-encryption เฉพาะ ให้ถอดรหัสก่อนสร้าง
• เมื่อไม่มี structure tree ตัวสร้างจะใช้เส้นทางที่ไม่ติดแท็กโดยอัตโนมัติ — แบบ heuristic หากเปิดใช้งาน มิฉะนั้นเป็น bare fallback
• ขีดจำกัดทรัพยากรใน AstBuildOptions (max nodes, max depth, max memory, wall-clock timeout) ทำให้เกิดข้อผิดพลาด build-limit หรือ build-timeout แทนที่จะเป็นงานที่ไม่มีขอบเขต
• cache key รวม source hash และ options hash ไว้ ดังนั้นการสร้างสองครั้งด้วยอินพุตและตัวเลือกที่เหมือนกันจะคืนค่า tree เดียวกัน
• AstNode ไม่เปลี่ยนแปลง ผู้บริโภคได้รับอินสแตนซ์ node ใหม่เมื่อ tree เปลี่ยน

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

ต่อไปนี้สะท้อน public API ที่บันทึกไว้ repository ไม่ได้มาพร้อมตัวอย่างที่รันได้สำหรับโมดูลนี้

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

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

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

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

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

• หน้าที่ content stream แยกวิเคราะห์ไม่ได้จะถูกข้ามระหว่างการแนบ bounding box tree ยังคงถูกคืนค่า เพียงแต่ไม่มี box สำหรับหน้าเหล่านั้น
• ตัวสร้างแบบ heuristic เป็นแบบเลือกใช้ เมื่อปิดใช้งาน PDF ที่ไม่ติดแท็กจะให้ tree ที่หยาบกว่าจาก bare fallback
• ช่วงหน้าใน AstBuildOptions ใช้ดัชนีแบบ 0-based และรวมปลายทั้งสอง การปล่อยขอบเขตทั้งสองเป็น null จะประมวลผลทุกหน้า

ประสิทธิภาพ

ต้นทุนการสร้างปรับขนาดตามจำนวน node และจำนวนหน้า AstBuildOptions จำกัดทั้งสอง แคช short-circuit การสร้างซ้ำของอินพุตเดียวกันด้วยตัวเลือกเดียวกัน NextPDF ไม่ได้เผยแพร่เวลาต่อเอกสารที่ตายตัวในที่นี้ wall-clock timeout (ค่าเริ่มต้น 30 s) และเพดาน node (ค่าเริ่มต้น 100,000) จำกัดงานในกรณีเลวร้ายที่สุด ให้วัดด้วยเอกสารที่เป็นตัวแทน

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

ถืออินพุตเป็นสิ่งที่ไม่น่าเชื่อถือ ตัวสร้างปฏิเสธ PDF ที่เข้ารหัสแทนที่จะประมวลผลบางส่วน เพดานทรัพยากร (node, depth, memory, time) ป้องกันเอกสารที่ผิดปกติหรือเป็นอันตราย โมดูลนี้ไม่บันทึกเนื้อหาเอกสาร

ความสอดคล้อง

เส้นทาง structure-tree อ่านโครงสร้าง tagged-PDF ที่กำหนดโดย ISO 32000-2 ซอร์สของโมดูลใส่คำอธิบายข้อ content-stream และ structure ที่เกี่ยวข้อง เนื่องจากคลังข้อมูล RAG ไม่พร้อมใช้งานในเวลาเขียน หน้านี้จึงไม่อ้างตัวระบุข้อภายนอกและจำกัดคำแถลงความสอดคล้องไว้ที่พฤติกรรมที่ตรวจสอบโดย test ของโมดูล

หมายเหตุขอบเขตของ Enterprise

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

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

หากไม่มี Pro จะไม่มีต้นไม้เอกสารที่เทียบเท่า ผู้เรียกใช้แยกวิเคราะห์ content stream โดยตรงโดยใช้ไพรมิทีฟของ NextPDF Core ดู /modules/ast/

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

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

ดูเพิ่มเติม

• AST — เอกสารอ้างอิงเชิงลึก
• Projection
• Diff
• Output Pipeline