Ast: ทรีเอกสารเชิงความหมายและซีเรียลไลเซชัน

ภาพรวมโดยย่อ

โมดูล Ast จัดเตรียมทรีไวยากรณ์เชิงนามธรรมของเอกสารเชิงความหมาย (AST) สำหรับเอนจิน โมดูลนี้จำลองเอกสารเป็นลำดับชั้นของโหนดที่มีชนิดกำกับ ได้แก่ Document, Section, Heading, Paragraph, List, Table, Figure, Code และ FormField โมเดลนี้เก็บ bounding box และจุดยึดการอ้างอิง แล้วทำซีเรียลไลเซชันเป็น JavaScript Object Notation (JSON) แบบกำหนดเวอร์ชัน เลเยอร์การแท็กเพื่อการเข้าถึงใช้ทรีนี้ในการสร้างทรีโครงสร้าง

ความเสถียร: experimental นี่เป็นพื้นผิวของโมเดลภายใน คลาสต่างๆ ของโมเดลนี้ ไม่ได้รับประกัน public application programming interface (API) ที่ตรึงตามเวอร์ชัน ชุดโหนดและแอตทริบิวต์ของโหนดอาจเปลี่ยนแปลงได้ สคีมาสำหรับการทำ ซีเรียลไลเซชัน ถูกกำหนดเวอร์ชันแยกต่างหาก (AstDocument::CURRENT_SCHEMA_VERSION = '1.0.0') ตัวซีเรียลไลเซอร์ตรวจจับ และปฏิเสธสคีมาที่เข้ากันไม่ได้ ดังนั้น AST JSON ที่จัดเก็บไว้จึงยังรักษาสัญญา ที่เสถียรไว้แม้ว่า API ในหน่วยความจำจะเปลี่ยนแปลงก็ตาม

การติดตั้ง

composer require nextpdf/core:^3

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

ในที่นี้ AST แสดงโครงสร้างเชิงตรรกะของเอกสาร AST ไม่ใช่ทรีไวยากรณ์ของพาร์เซอร์สำหรับรูปแบบอินพุตเพียงรูปแบบเดียว AstDocument คือคอนเทนเนอร์ ภายในมี AstNode ราก (ซึ่งต้องเป็น NodeType::Document), เวอร์ชันสคีมา, แฮชของไฟล์ Portable Document Format (PDF) ต้นทาง และจำนวนหน้า คอนเทนเนอร์นี้ปฏิเสธการสร้างที่ไม่ถูกต้อง รวมถึงเวอร์ชันสคีมาที่ว่างเปล่า จำนวนหน้าน้อยกว่าหนึ่ง หรือชนิดของรากที่ไม่ถูกต้อง

AstNode คือโหนดแบบเรียกซ้ำ NodeType ระบุชนิดเชิงความหมายทั้งหมด โหนดแต่ละโหนดมีโหนดลูก, BoundingBox แบบไม่บังคับ, เนื้อหาข้อความแบบไม่บังคับ และแอตทริบิวต์ที่ตรวจสอบความถูกต้องโดย NodeAttributeSchema API ของโหนดรองรับการสร้างค่าต่อยอดแบบไม่เปลี่ยนแปลงค่า withBboxAndText() คืนค่าโหนดใหม่ deepClone() คัดลอกทรีย่อย NodeId คืออัตลักษณ์แบบ value object CitationAnchor ผูกโหนดเข้ากับตำแหน่งต้นทางเพื่อให้สืบย้อนกลับได้ AstNodeCollection คือเซตแบบ Countable/IteratorAggregate ที่ใช้ ofType() สำหรับกรอง

AstSerializer คือขอบเขตสำหรับการคงสภาพข้อมูล serialize() เขียน AstDocument ออกเป็น JSON deserialize() อ่านข้อมูลกลับคืนมา canDeserialize() และ extractSchemaVersion() ให้คุณตรวจสอบความเข้ากันได้ก่อนดีซีเรียลไลซ์ ดังนั้นความไม่ตรงกันของสคีมาจึงเป็นเงื่อนไขที่ตรวจพบได้ แทนที่จะกลายเป็นการโหลดข้อมูลที่เสียหาย AstDocument::estimateTokenCount() ช่วยประเมินขนาดของเนื้อหาสำหรับการประมวลผลปลายทางที่จำกัดด้วยจำนวนโทเค็น

พื้นผิว API

คลาส	สมาชิกหลัก	บทบาท
AstDocument	toJson(), nodeCount(), estimateTokenCount(), CURRENT_SCHEMA_VERSION	คอนเทนเนอร์ราก ตรวจสอบความถูกต้องของชนิดรากและสคีมา
AstNode	addChild(), children(), childCount(), totalNodeCount(), withBboxAndText(), deepClone()	โหนดเชิงความหมายแบบเรียกซ้ำ
NodeType (enum)	Document, Heading, Table, Figure, FormField, …	ชนิดของโหนดเชิงความหมาย
AstNodeCollection	add(), count(), isEmpty(), ofType(), toArray()	เซตโหนดที่วนซ้ำได้และกรองตามชนิดได้
AstSerializer	serialize(), deserialize(), canDeserialize(), extractSchemaVersion()	การคงสภาพข้อมูล JSON แบบกำหนดเวอร์ชัน
BoundingBox	toArray(), equals()	value object เชิงเรขาคณิต (เปรียบเทียบแบบเอปไซลอน)
NodeId / CitationAnchor	toString(), equals(), toArray()	อัตลักษณ์ของโหนดและจุดยึดสำหรับการสืบย้อนไปยังต้นทาง
NodeAttributeSchema	การตรวจสอบความถูกต้องของแอตทริบิวต์	สคีมาสำหรับแอตทริบิวต์ของโหนด

เรียกใช้ composer docs:generate-api-php -- --module=Ast เพื่อสร้างตาราง PHPDoc ฉบับเต็ม

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

สร้างทรีขนาดเล็ก แล้วทำซีเรียลไลเซชัน

<?php

declare(strict_types=1);

require_once __DIR__ . '/../vendor/autoload.php';

use NextPDF\Ast\AstNode;
use NextPDF\Ast\AstSerializer;
use NextPDF\Ast\NodeType;

$root = new AstNode(NodeType::Document);
$heading = new AstNode(NodeType::Heading);
$root->addChild($heading);
$root->addChild(new AstNode(NodeType::Paragraph));

echo "Nodes: {$root->totalNodeCount()}\n";

$json = (new AstSerializer())->serialize(/* an AstDocument wrapping $root */);

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

ทำ round-trip กับ AST ที่จัดเก็บไว้อย่างระมัดระวัง ตรวจสอบความเข้ากันได้ของสคีมาก่อนดีซีเรียลไลซ์ JSON ที่ไม่น่าเชื่อถือ

<?php

declare(strict_types=1);

require_once __DIR__ . '/../vendor/autoload.php';

use NextPDF\Ast\AstDocument;
use NextPDF\Ast\AstSerializer;
use Psr\Log\LoggerInterface;

final readonly class AstStore
{
    public function __construct(
        private AstSerializer $serializer,
        private LoggerInterface $logger,
    ) {}

    public function load(string $json): ?AstDocument
    {
        if (!$this->serializer->canDeserialize($json)) {
            $this->logger->warning('AST JSON schema incompatible; rejected.', [
                'found_schema' => $this->serializer->extractSchemaVersion($json),
                'expected'     => AstDocument::CURRENT_SCHEMA_VERSION,
            ]);

            return null;
        }

        return $this->serializer->deserialize($json);
    }
}

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

• AstDocument กำหนดให้โหนดรากต้องเป็น NodeType::Document ทรีที่มีรากเป็นชนิดอื่นจะโยนข้อยกเว้นเมื่อสร้าง
• AstNode::withBboxAndText() และ deepClone() คืนค่าอินสแตนซ์ใหม่ เมธอดที่แก้ไขโหนดซึ่งมีให้ (addChild()) จะเปลี่ยนแปลงค่าของโหนด ส่วนตัวช่วยสำหรับการสร้างค่าต่อยอดจะไม่เปลี่ยนแปลงค่า โปรดระวังว่ากำลังเรียกเมธอดใด
• ควบคุม deserialize() ด้วย canDeserialize() เสมอสำหรับ JSON ที่มาจากภายนอก ความไม่ตรงกันของเวอร์ชันสคีมาเป็นเงื่อนไขที่ตรวจพบได้และคาดการณ์ได้
• estimateTokenCount() เป็นค่าประมาณสำหรับกำหนดขนาดของการประมวลผลปลายทาง ไม่ใช่จำนวนโทเค็นที่แน่นอนจากตัวแปลงโทเค็น อย่าถือว่าค่านี้เป็นค่าทางการ
• BoundingBox::equals() เป็นการเปรียบเทียบแบบเอปไซลอน (ค่าเริ่มต้น 0.001) การเท่ากันแบบแม่นตรงของ float ไม่ใช่สัญญาที่รับประกัน

ประสิทธิภาพ

การสร้างทรีและการไล่ผ่านทรีมีความซับซ้อน O(n) ตามจำนวนโหนด การทำซีเรียลไลเซชันเป็นเชิงเส้นตามขนาดของทรี โปรไฟล์ความสามารถในการทำซ้ำคือ bitwise ทรีเดียวกันจะถูกทำซีเรียลไลเซชันเป็นไบต์ JSON ชุดเดียวกัน ซึ่งทำให้สคีมายังคงเสถียรในฐานะสัญญาของการคงสภาพข้อมูล เวิร์กโหลดอ้างอิงเริ่มต้นอยู่ภายในงบประมาณ 1500 ms wall / 64 MB peak อย่างเหลือเฟือ

หมายเหตุด้านความปลอดภัย

AstSerializer::deserialize() ดีซีเรียลไลซ์ JSON ที่อาจถูกจัดเก็บไว้หรือถูกส่งผ่าน ตรวจสอบความเข้ากันได้ด้วย canDeserialize() ก่อน ถือว่าเนื้อหาข้อความและแอตทริบิวต์ของทรีที่ดีซีเรียลไลซ์แล้วเป็นสตริงที่ไม่น่าเชื่อถือ เมื่อข้อมูลเหล่านั้นกลับเข้าสู่แอปพลิเคชันหรือถูกเรนเดอร์ โมดูลนี้ไม่ทำ input/output (I/O) ใดๆ และไม่ฝังข้อมูลภายนอกใดๆ ดูแบบจำลองภัยคุกคามของเอนจินได้ที่พาธ /modules/core/security/ ในที่เก็บนี้

ความสอดคล้องตามข้อกำหนด

โมดูลนี้ไม่ยืนยันข้ออ้างเชิงบรรทัดฐานใดๆ ตามข้อกำหนด PDF AST เชิงความหมายเป็นนามธรรมภายในของเอนจิน AST ไม่ได้นำแบบจำลองเอกสารมาตรฐานที่ต้องอ้างอิงข้อกำหนดมาใช้งาน ในกรณีที่ AST ป้อนข้อมูลให้กับการแท็กเพื่อการเข้าถึง ความสอดคล้องตาม PDF/UA และ tagged-PDF ของ เอาต์พุต จะถูกบันทึกและตรวจสอบความถูกต้องที่ /modules/core/accessibility/ และ /modules/core/conformance/ ไม่ใช่ที่นี่

ดูเพิ่มเติม

• โมดูล Accessibility — ใช้ AST เพื่อสร้างทรีโครงสร้าง
• โมดูล Inspect — ตรวจสอบเค้าโครงและโครงสร้าง
• โมดูล HTML — เป็นแหล่งของโครงสร้างเอกสาร
• ภาพรวมความสอดคล้องตามข้อกำหนด