สังเกตเหตุการณ์ในวงจรชีวิตของ PDF เมื่อฝัง NextPDF Connect

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

คุณสามารถสังเกตและตอบสนองต่อเหตุการณ์ในวงจรชีวิตของ PDF ได้ เช่น การสร้างเอกสาร การเพิ่มหน้า การโหลดฟอนต์ การใช้ลายเซ็น และการสร้างเอาต์พุต โดยไม่ต้องสร้างคลาสย่อยของเอกสาร นี่คือความสามารถสำหรับการฝังไลบรารี ไม่ใช่เครื่องมือ Connect พื้นผิว transport ของ Connect แบบรีโมต (Model Context Protocol (MCP) / REST / gRPC) ไม่เปิดเผยเครื่องมือ event-listener ใดๆ คุณจะสังเกตเหตุการณ์ได้เฉพาะเมื่อโฮสต์เอนจินแบบ in-process และเชื่อมต่อ dispatcher แล้วเท่านั้น หน้านี้กำหนดขอบเขตดังกล่าวและแสดงรูปแบบ in-process อย่างชัดเจน เพื่อให้ผู้เรียกใช้ไม่คาดหวัง hook แบบรีโมต

การติดตั้ง

composer require nextpdf/server

ใช้รูปแบบนี้เมื่อแอปพลิเคชันของคุณฝังเอนจินและเรียกใช้งานโดยตรงใน PHP เช่น จากโฮสต์เซิร์ฟเวอร์ที่กำหนดเอง สำหรับ transport แบบรีโมต ให้สังเกตระบบที่ขอบเขตของ transport ด้วย telemetry แทน

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

เอนจินจะปล่อยเหตุการณ์ผ่าน dispatcher ตามแนว PSR-14 คุณสร้าง listener provider และ dispatcher ลงทะเบียน listener ตามคลาสเหตุการณ์ แล้วแนบ dispatcher เข้ากับเอกสาร จากนั้นเหตุการณ์จะถูกปล่อยโดยอัตโนมัติระหว่างที่สร้างเอกสาร เมื่อไม่มี dispatcher แนบอยู่ ระบบเหตุการณ์จะไม่เพิ่มต้นทุนใดๆ เพราะจุดส่งทุกจุดเป็นการตรวจสอบ null ระบบจะแปลงคลาสผ่านการแมป class→file ของ autoload (PSR-4 §3) และโค้ดตัวอย่างทั้งหมดประกาศ strict types พร้อมปฏิบัติตามมาตรฐานการเขียนโค้ด (PSR-12 §2.1)

พื้นผิว API

หน้านี้ ไม่มีเครื่องมือ Connect สำหรับ event hook แคตตาล็อกเครื่องมือ คือแคตตาล็อกอ้างอิงอย่างเป็นทางการ และไม่มีรายการ event hook ใดๆ พื้นผิวแบบ in-process คือคลาสเหตุการณ์ของเอนจิน (DocumentCreatedEvent, PageAddedEvent, FontLoadedEvent, SignatureAppliedEvent, EncryptionAppliedEvent, DocumentOutputEvent) ร่วมกับ listener provider และ dispatcher เครื่องมือที่ใช้งานได้ผ่าน transport ขึ้นอยู่กับ tier ที่ติดตั้ง และ event hook ไม่เคยอยู่ในกลุ่มนั้น

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

<?php

declare(strict_types=1);

use NextPDF\Core\Document;
use NextPDF\Event\EventDispatcher;
use NextPDF\Event\ListenerProvider;
use NextPDF\Event\Document\DocumentCreatedEvent;
use NextPDF\Event\Document\PageAddedEvent;

$provider = new ListenerProvider();
$dispatcher = new EventDispatcher($provider);

$provider->addListener(
    DocumentCreatedEvent::class,
    static function (DocumentCreatedEvent $event): void {
        // react to creation
    },
);

$provider->addListener(
    PageAddedEvent::class,
    static function (PageAddedEvent $event): void {
        // react to a new page: $event->pageIndex
    },
);

$pdf = Document::createStandalone();
$pdf->setEventDispatcher($dispatcher);
$pdf->addPage()->setFont('Helvetica', '', 12)->cell(0, 10, 'Hello')->save('/tmp/out.pdf');

ตัวอย่างโค้ด — สำหรับใช้งานจริง

รูปแบบ in-process ที่ใช้บ่อยมีดังนี้:

• การบันทึกการตรวจสอบ ลงทะเบียน listener บนคลาสเหตุการณ์พื้นฐานด้วย priority ต่ำเพื่อให้ทำงานท้ายสุดเสมอ จากนั้นบันทึกชื่อเหตุการณ์และบริบท
• การบังคับใช้ใบอนุญาต/ขีดจำกัด ฟังบน PageAddedEvent ด้วย priority สูง เมื่อจำนวนหน้าเกินขีดจำกัด ให้หยุดการแพร่กระจายและโยน exception แบบมีชนิด
• การประมวลผลภายหลัง ฟังบน DocumentOutputEvent แล้วแปลงไบต์ของ PDF ก่อนส่งคืน
• การเฝ้าระวังด้านความปลอดภัย ฟังบน SignatureAppliedEvent / EncryptionAppliedEvent แล้วบันทึก level/algorithm และแฟล็กสิทธิ์ลงในบันทึกการตรวจสอบ

แนวทาง priority: ใช้ ≥1000 สำหรับการตรวจสอบ security/limit ใช้ 0 สำหรับ listener ทั่วไป และใช้ ≤−1000 สำหรับ audit/telemetry

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

• ไม่พร้อมใช้งานผ่าน transport แบบรีโมต ไคลเอนต์ MCP/REST/gRPC แบบรีโมตไม่สามารถลงทะเบียน listener ได้ ดังนั้นอย่าจัดทำเอกสารหรือคาดหวังว่าจะมี hook แบบรีโมต
• จะไม่มี overhead ก็ต่อเมื่อไม่มี dispatcher เท่านั้น การแนบ dispatcher จะเพิ่มต้นทุนของ listener ที่อยู่ในนั้น ดังนั้นควรให้ listener บนเส้นทางที่ทำงานบ่อยมีต้นทุนต่ำ
• การควบคุมการแพร่กระจาย การหยุดการแพร่กระจายจะป้องกันไม่ให้ listener ที่อยู่ถัดไปทำงาน ดังนั้นจัดลำดับตาม priority อย่างรอบคอบ

ประสิทธิภาพ

เมื่อไม่มี dispatcher ต้นทุนจะเป็นศูนย์ เมื่อมี listener ต้นทุนจะเท่ากับผลรวมของงานที่ listener ทั้งหมดทำ โปรไฟล์เป็นแบบ structural สำหรับเอกสารที่ถูกสร้างขึ้น

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

listener สามารถเห็นเหตุการณ์การลงนามและการเข้ารหัสลับได้ ดังนั้นให้ถือว่า audit sink ทุกจุดเป็นข้อมูลอ่อนไหว listener สำหรับการประมวลผลภายหลังที่เปลี่ยนแปลงไบต์เอาต์พุตเป็นจุดที่ต้องไว้วางใจ จึงควรมีให้น้อยที่สุดและต้องผ่านการตรวจทาน

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

ข้อความ	ข้อกำหนด	ข้อ	รหัสอ้างอิง (reference_id)
ระบบแปลงคลาสเหตุการณ์ผ่านการแมปของ autoload	PSR-4	§3
โค้ดตัวอย่างประกาศ strict types ตามมาตรฐาน	PSR-12	§2.1

บริบทเชิงพาณิชย์

ไม่เกี่ยวข้อง — ระบบเหตุการณ์เป็นส่วนของ Core และไม่ได้เป็นส่วนหนึ่งของพื้นผิวเครื่องมือ Connect แบบรีโมต

ความพร้อมใช้งานตาม transport

ช่องทางขนส่ง (Transport)	พร้อมใช้งาน	หมายเหตุ
MCP (stdio)	ไม่	ไม่เปิดเผยเครื่องมือ event-listener
REST	ไม่	ไม่มี endpoint สำหรับ event-listener
gRPC	ไม่	ไม่มี RPC สำหรับ event-listener
In-process (การฝังไลบรารี)	ใช่	รูปแบบ dispatcher แบบ PSR-14 ข้างต้น

สำหรับการปรับใช้แบบรีโมต ให้สังเกตที่ขอบเขตของ transport ด้วย telemetry แทนการคาดหวัง event hook ของเอนจิน

ระดับความเสี่ยง HITL

ไม่เกี่ยวข้อง — หน้านี้ไม่มีเครื่องมือ Connect จึงไม่เกี่ยวข้องกับ confirmation gate โฮสต์ต้องป้องกันการประมวลผลภายหลังแบบ in-process ใดๆ ที่เขียนไฟล์

JSON envelope ของ confirmation gate

ไม่เกี่ยวข้อง — ไม่มีการเรียกเครื่องมือ (สำหรับการกำหนด gate ของการเรียกเครื่องมือ ดู output-approval)

ดูเพิ่มเติม

• วงจรชีวิตที่ปลอดภัยสำหรับ worker
• การจัดการข้อผิดพลาด
• แคตตาล็อกเครื่องมือ